sentinelforge 0.4.0__tar.gz

sentinelforge-0.4.0/.env.example

@@ -0,0 +1,57 @@
+# SentinelForge Environment Configuration
+# Copy this to .env and fill in your values.
+# NEVER commit .env to version control.
+
+# --- Core ---
+SF_ENVIRONMENT=development
+SF_SIMULATION_MODE=true
+SF_DEBUG=false
+
+# --- Authentication ---
+# JWT secret for API authentication (minimum 32 characters)
+# Generate with: python -c "import secrets; print(secrets.token_hex(32))"
+SF_AUTH__ENABLED=false
+SF_AUTH__JWT_SECRET=
+SF_AUTH__DASHBOARD_PASSWORD=changeme
+
+# --- LLM Provider ---
+# Supported: ollama, anthropic, openai
+SF_LLM__PROVIDER=ollama
+SF_LLM__MODEL=llama3.1:8b
+SF_LLM__BASE_URL=http://localhost:11434
+SF_LLM__API_KEY=
+
+# --- Database ---
+SF_DATABASE_PATH=./data/sentinelforge.db
+SF_AUDIT_LOG_PATH=./data/audit.log
+SF_VECTOR_DB_PATH=./data/vector_db
+
+# --- API ---
+SF_API__HOST=0.0.0.0
+SF_API__PORT=8000
+SF_API__RATE_LIMIT_PER_MINUTE=60
+SF_API__MAX_REQUEST_SIZE_KB=1024
+
+# --- Alerting ---
+SF_ALERTS__ENABLED=true
+SF_ALERTS__CONSOLE_ALERTS=true
+SF_ALERTS__WEBHOOK_ENABLED=false
+SF_ALERTS__WEBHOOK_URL=
+SF_ALERTS__MIN_SEVERITY=high
+
+# --- Slack (optional) ---
+SF_SLACK_WEBHOOK_URL=
+SF_SLACK_CHANNEL=#security-alerts
+
+# --- Email (optional) ---
+SF_SMTP_HOST=
+SF_SMTP_PORT=587
+SF_SMTP_USER=
+SF_SMTP_PASSWORD=
+SF_SMTP_FROM=sentinelforge@example.com
+SF_SMTP_TO=security-team@example.com
+
+# --- External Integrations ---
+SF_SIEM_API_KEY=
+SF_OTX_API_KEY=
+SF_MISP_API_KEY=

sentinelforge-0.4.0/.github/workflows/ci.yml

@@ -0,0 +1,49 @@
+name: CI
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install ruff
+        run: pip install ruff
+      - name: Run linter
+        run: ruff check src/ tests/
+
+  test:
+    runs-on: ubuntu-latest
+    needs: lint
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: pip
+      - name: Install dependencies
+        run: pip install -e ".[all]"
+      - name: Run tests
+        run: python -m pytest tests/ -v --tb=short
+      - name: Run evaluation harness
+        run: python -m sentinelforge.cli evaluate
+
+  security:
+    runs-on: ubuntu-latest
+    needs: lint
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install bandit
+        run: pip install bandit
+      - name: Run security scan
+        run: bandit -r src/sentinelforge/ -ll -ii --skip B101,B404,B603

sentinelforge-0.4.0/.github/workflows/release.yml

@@ -0,0 +1,64 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: write
+  packages: write
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: pip
+      - name: Install dependencies
+        run: pip install -e ".[all]"
+      - name: Run tests
+        run: python -m pytest tests/ -v --tb=short
+      - name: Run evaluation
+        run: python -m sentinelforge.cli evaluate
+
+  docker:
+    runs-on: ubuntu-latest
+    needs: test
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+      - name: Log in to GHCR
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      - name: Extract version from tag
+        id: version
+        run: echo "VERSION=${GITHUB_REF#refs/tags/v}" >> $GITHUB_OUTPUT
+      - name: Build and push Docker image
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          file: docker/Dockerfile
+          push: true
+          tags: |
+            ghcr.io/${{ github.repository }}:${{ steps.version.outputs.VERSION }}
+            ghcr.io/${{ github.repository }}:latest
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+
+  github-release:
+    runs-on: ubuntu-latest
+    needs: [test, docker]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true

sentinelforge-0.4.0/.gitignore

@@ -0,0 +1,52 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.venv/
+venv/
+env/
+.env
+*.env.local
+*.env.production
+
+# Logs
+logs/
+*.log
+
+# Data (keep sample, ignore runtime)
+data/vector_db/
+data/audit.log
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Docker
+.docker/
+
+# Test artifacts
+.pytest_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+
+# Database runtime
+data/*.db
+data/*.db-wal
+data/*.db-shm
+
+# Secrets - never commit
+*.pem
+*.key
+secrets/

sentinelforge-0.4.0/CONTRIBUTING.md

@@ -0,0 +1,91 @@
+# Contributing to SentinelForge
+
+Thank you for your interest in contributing. SentinelForge is a security-critical project — contributions are welcome but must meet safety and quality standards.
+
+## Getting Started
+
+```bash
+git clone https://github.com/SageshAdhikari/SentinelForge.git
+cd SentinelForge
+make install        # Linux/Mac
+# .\scripts\setup_windows.ps1   # Windows
+make test
+```
+
+## Development Workflow
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/my-feature`)
+3. Write tests for new functionality
+4. Ensure all tests pass (`pytest tests/ -v`)
+5. Run linting (`ruff check src/`)
+6. Submit a pull request with a clear description
+
+## Code Standards
+
+- **Python 3.11+** required
+- **Type hints** on all public functions
+- **Pydantic models** for data validation
+- **structlog** for logging (never `print()`)
+- **ruff** for linting (config in `pyproject.toml`)
+- Keep functions short and focused
+
+## Security Requirements
+
+Every contribution must follow these rules:
+
+1. **Never introduce hardcoded secrets** — use environment variables or `.env`
+2. **Never bypass the Guardian agent** — all actions must be validated
+3. **Never add irreversible actions** without human approval gates
+4. **Always sanitize user input** through the SafetyEngine
+5. **Never log sensitive data** — use `redact()` from `core/secrets.py`
+6. **Add tests** for any security-relevant code
+7. **Keep the audit hash chain intact** — never modify the AuditLogger interface
+
+## Adding a New Agent
+
+1. Create `src/sentinelforge/agents/your_agent.py`
+2. Extend `BaseAgent` and implement `async def run(self, state) -> OrchestratorState`
+3. Register in `core/orchestrator.py`
+4. Add tests in `tests/test_agents.py`
+5. Update the README architecture diagram
+
+## Adding a New Connector
+
+1. Create a class extending the appropriate ABC in `connectors/`
+2. Register it in the config system (`core/config.py`)
+3. Add tests
+4. Document in README
+
+## Adding New Detection Signatures
+
+1. Add to `ANOMALY_SIGNATURES` in `agents/monitor.py`
+2. Include: regex pattern, severity, MITRE technique IDs, description
+3. Add test cases
+4. Add the MITRE technique to `MITRE_LABELS` in `dashboard/app.py`
+
+## Testing
+
+```bash
+# Run all tests
+pytest tests/ -v
+
+# Run specific test file
+pytest tests/test_safety.py -v
+
+# Run evaluation harness
+sentinelforge evaluate
+```
+
+All PRs must pass:
+- All existing tests (currently 166+)
+- All 3 evaluation scenarios (brute_force, ransomware, lateral_movement)
+- Ruff linting with no errors
+
+## Reporting Security Vulnerabilities
+
+If you find a security vulnerability, **do not open a public issue**. Instead, email the maintainers directly. We will respond within 48 hours.
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.

sentinelforge-0.4.0/DEPLOYMENT.md

@@ -0,0 +1,278 @@
+# SentinelForge Deployment Guide
+
+## Prerequisites
+
+- Python 3.11+
+- Docker & Docker Compose (for containerized deployment)
+- Ollama (optional, for local LLM inference)
+
+---
+
+## Quick Start (Development)
+
+### Windows
+
+```powershell
+powershell -ExecutionPolicy Bypass -File scripts/setup_windows.ps1
+```
+
+### Linux / macOS
+
+```bash
+bash scripts/setup_linux.sh
+```
+
+### Manual Setup
+
+```bash
+python -m venv .venv
+source .venv/bin/activate    # Linux/macOS
+# .venv\Scripts\activate     # Windows
+
+pip install -e ".[all]"
+cp .env.example .env
+# Edit .env with your configuration
+
+mkdir -p data logs
+
+# Run tests to verify
+python -m pytest tests/ -q
+
+# Run a simulation
+sentinelforge run --scenario brute_force
+```
+
+---
+
+## Docker Deployment
+
+### Architecture
+
+```
+┌──────────────┐  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐
+│  API Server  │  │    Worker    │  │  Dashboard   │  │    Ollama    │
+│  :8000       │  │  (one-shot)  │  │  :8501       │  │  :11434      │
+│  FastAPI     │  │  Defense     │  │  Streamlit   │  │  Local LLM   │
+│              │  │  Cycles      │  │              │  │              │
+└──────┬───────┘  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘
+       │                 │                 │                 │
+       └─────────────────┴─────────────────┴─────────────────┘
+                         sentinelforge-net (bridge)
+```
+
+### Steps
+
+```bash
+# 1. Configure environment
+cp .env.example .env
+# Edit .env — set at minimum:
+#   SF_AUTH__JWT_SECRET (generate with: python -c "import secrets; print(secrets.token_hex(32))")
+#   SF_AUTH__DASHBOARD_PASSWORD
+
+# 2. Build and start
+docker compose build
+docker compose up -d
+
+# 3. (Optional) Pull Ollama model for LLM analysis
+docker exec sentinelforge-ollama ollama pull llama3.1:8b
+
+# 4. Verify
+curl http://localhost:8000/health
+# Open http://localhost:8501 for dashboard
+```
+
+### Services
+
+| Service | Port | Purpose |
+|---------|------|---------|
+| sentinelforge-api | 8000 | REST API, event submission, defense cycles |
+| sentinelforge-worker | - | Runs defense cycles (one-shot, restarts manually) |
+| sentinelforge-dashboard | 8501 | Streamlit web UI |
+| sentinelforge-ollama | 11434 (localhost only) | Local LLM inference |
+
+### Volumes
+
+| Volume | Purpose |
+|--------|---------|
+| sf-data | SQLite database, audit logs, vector DB |
+| sf-logs | Application logs, alert logs |
+| ollama-models | Downloaded LLM models |
+
+---
+
+## Production Checklist
+
+### Security
+
+- [ ] Set a strong `SF_AUTH__JWT_SECRET` (64+ hex chars)
+- [ ] Set `SF_AUTH__ENABLED=true`
+- [ ] Change `SF_AUTH__DASHBOARD_PASSWORD` from default
+- [ ] Set `SF_SIMULATION_MODE=true` initially, switch to `false` only after testing
+- [ ] Review `configs/default.yaml` allowed/blocked action lists
+- [ ] Restrict CORS origins to your dashboard domain
+- [ ] Place the API behind a reverse proxy (nginx/Caddy) with TLS
+
+### Monitoring
+
+- [ ] Enable file alerts: `SF_ALERTS__FILE_ALERTS=true`
+- [ ] Configure Slack webhooks: `SF_SLACK_WEBHOOK_URL=https://hooks.slack.com/...`
+- [ ] Configure email alerts: set `SF_SMTP_*` variables
+- [ ] Set up syslog forwarding: `SF_SYSLOG_HOST=your-siem.example.com`
+- [ ] Verify audit chain periodically: `sentinelforge audit --verify`
+
+### Infrastructure
+
+- [ ] Back up `data/sentinelforge.db` and `data/audit.log` regularly
+- [ ] Set up log rotation (Docker json-file driver handles this)
+- [ ] Monitor container health: `docker compose ps`
+- [ ] Set resource limits appropriate to your hardware
+
+---
+
+## LLM Configuration
+
+SentinelForge works in three modes:
+
+### 1. Rule-Based (No LLM)
+
+Default mode. No API keys needed. Uses pattern matching and heuristics.
+
+```bash
+sentinelforge run --scenario brute_force
+```
+
+### 2. Local LLM (Ollama)
+
+Private, no data leaves your network.
+
+```bash
+# Install Ollama: https://ollama.com
+ollama pull llama3.1:8b
+
+# Set in .env:
+SF_LLM__PROVIDER=ollama
+SF_LLM__BASE_URL=http://localhost:11434
+SF_LLM__MODEL=llama3.1:8b
+
+sentinelforge run --scenario brute_force --llm
+```
+
+### 3. Cloud LLM (Anthropic / OpenAI)
+
+Higher quality analysis, requires API key.
+
+```bash
+# Anthropic
+SF_LLM__PROVIDER=anthropic
+SF_LLM__API_KEY=sk-ant-...
+
+# OpenAI
+SF_LLM__PROVIDER=openai
+SF_LLM__API_KEY=sk-...
+
+sentinelforge run --scenario brute_force --llm
+```
+
+**Auto-detection:** If `SF_LLM__PROVIDER` is not set, the system checks for `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, and `OLLAMA_HOST` environment variables in order.
+
+---
+
+## Alerting Configuration
+
+### Slack
+
+```bash
+SF_SLACK_WEBHOOK_URL=https://hooks.slack.com/services/T00/B00/xxx
+SF_SLACK_CHANNEL=#security-alerts
+```
+
+### Email (SMTP)
+
+```bash
+SF_SMTP_HOST=smtp.gmail.com
+SF_SMTP_PORT=587
+SF_SMTP_USER=alerts@example.com
+SF_SMTP_PASSWORD=app-password
+SF_SMTP_FROM=sentinelforge@example.com
+SF_SMTP_TO=security-team@example.com
+```
+
+### Syslog (RFC 5424)
+
+```bash
+SF_SYSLOG_HOST=siem.example.com
+SF_SYSLOG_PORT=514
+SF_SYSLOG_PROTO=udp    # or tcp
+```
+
+---
+
+## API Authentication
+
+### Generate a JWT Secret
+
+```bash
+python -c "import secrets; print(secrets.token_hex(32))"
+```
+
+### Login and Get Token
+
+```bash
+curl -X POST http://localhost:8000/api/v1/auth/login \
+  -H "Content-Type: application/json" \
+  -d '{"username": "admin", "password": "your-dashboard-password"}'
+```
+
+### Use the Token
+
+```bash
+curl -H "Authorization: Bearer <token>" \
+  http://localhost:8000/api/v1/audit
+```
+
+---
+
+## Troubleshooting
+
+### Tests Failing
+
+```bash
+# Reset singletons and run tests
+python -m pytest tests/ -v --tb=short
+```
+
+### Database Issues
+
+```bash
+# The database auto-creates on startup. To reset:
+rm data/sentinelforge.db
+sentinelforge run --scenario brute_force
+```
+
+### Audit Chain Broken
+
+```bash
+sentinelforge audit --verify
+# If broken, the old log can be archived and a new chain starts
+mv data/audit.log data/audit.log.bak
+```
+
+### Ollama Not Connecting
+
+```bash
+# Check Ollama is running
+curl http://localhost:11434/api/tags
+
+# In Docker, ensure the service name is used
+SF_LLM__BASE_URL=http://ollama:11434
+```
+
+### Dashboard Not Loading
+
+```bash
+# Check if Streamlit is installed
+pip install streamlit plotly
+
+# Run directly
+python -m streamlit run src/sentinelforge/dashboard/app.py
+```

sentinelforge-0.4.0/DISCLAIMER.md

@@ -0,0 +1,58 @@
+# Disclaimer & Liability Notice
+
+## Important Safety Warning
+
+SentinelForge is an **AI-powered autonomous cyber defense framework** that can
+execute real containment actions on live systems including:
+
+- Blocking IP addresses via firewall rules
+- Isolating hosts from the network
+- Killing running processes
+- Disabling user accounts
+- Quarantining files
+
+## Use at Your Own Risk
+
+**BY USING THIS SOFTWARE, YOU ACKNOWLEDGE AND AGREE THAT:**
+
+1. **No Warranty.** This software is provided "AS IS" without warranty of any
+   kind. The authors make no guarantees about the correctness, reliability, or
+   safety of any automated actions taken by this system.
+
+2. **Potential for Damage.** Automated containment actions can disrupt
+   legitimate services, lock out authorized users, and cause data loss. Always
+   run in **simulation mode** first and thoroughly test in an isolated
+   environment before enabling real execution.
+
+3. **Human Oversight Required.** This software is designed to assist human
+   security analysts, not replace them. Critical actions require human approval
+   by default. Disabling the approval workflow is done at your own risk.
+
+4. **AI Limitations.** The LLM-powered analysis can produce incorrect
+   assessments, false positives, or miss real threats. Never rely solely on
+   automated analysis for critical security decisions.
+
+5. **Compliance.** You are responsible for ensuring your use of this software
+   complies with all applicable laws, regulations, and organizational policies.
+   Automated IP blocking and account disabling may have legal implications in
+   your jurisdiction.
+
+6. **No Liability.** The authors and contributors shall not be liable for any
+   direct, indirect, incidental, special, exemplary, or consequential damages
+   arising from the use of this software.
+
+## Recommended Precautions
+
+- Always start with `SIMULATION_MODE=true`
+- Enable `CANARY_MODE=true` for dry-run previews before execution
+- Set `REQUIRE_HUMAN_APPROVAL=true` for all critical actions
+- Test in an isolated lab environment before any production deployment
+- Maintain manual override access to all systems SentinelForge manages
+- Keep audit logging enabled and review logs regularly
+- Set up alerting (Slack/Email/Syslog) for immediate visibility
+
+## Contact
+
+For security vulnerabilities, please email: sageshadhikari@gmail.com
+
+Do NOT open public issues for security vulnerabilities.

sentinelforge-0.4.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sagesh Adhikari
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.