{"id":48381020,"url":"https://github.com/for-sunny/sentinel-shield","last_synced_at":"2026-04-05T20:03:28.578Z","repository":{"id":339317843,"uuid":"1153228674","full_name":"For-Sunny/SENTINEL-SHIELD","owner":"For-Sunny","description":"Defense-only AI attack detection daemon for small businesses. Watches logs, detects AI-orchestrated cyberattacks, blocks malicious IPs. Hebbian learning. MITRE ATT\u0026CK mapped. Apache 2.0.","archived":false,"fork":false,"pushed_at":"2026-02-19T04:43:33.000Z","size":154,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-02-19T10:50:46.406Z","etag":null,"topics":["ai-security","cybersecurity","hebbian-learning","intrusion-detection","log-analysis","mitre-attack","python","security","small-business","threat-detection"],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/For-Sunny.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-09T03:58:27.000Z","updated_at":"2026-02-19T04:43:36.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/For-Sunny/SENTINEL-SHIELD","commit_stats":null,"previous_names":["for-sunny/sentinel-shield"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/For-Sunny/SENTINEL-SHIELD","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/For-Sunny%2FSENTINEL-SHIELD","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/For-Sunny%2FSENTINEL-SHIELD/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/For-Sunny%2FSENTINEL-SHIELD/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/For-Sunny%2FSENTINEL-SHIELD/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/For-Sunny","download_url":"https://codeload.github.com/For-Sunny/SENTINEL-SHIELD/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/For-Sunny%2FSENTINEL-SHIELD/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31448219,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-05T15:22:31.103Z","status":"ssl_error","status_checked_at":"2026-04-05T15:22:00.205Z","response_time":75,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-security","cybersecurity","hebbian-learning","intrusion-detection","log-analysis","mitre-attack","python","security","small-business","threat-detection"],"created_at":"2026-04-05T20:03:25.657Z","updated_at":"2026-04-05T20:03:28.573Z","avatar_url":"https://github.com/For-Sunny.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SENTINEL Shield\n\nA Rust security daemon that watches your server logs, detects AI-orchestrated cyberattacks, and blocks malicious IPs. Built for small companies that can't afford a SOC team but still face automated threats.\n\nSENTINEL Shield is defense-only by architecture. It cannot attack. It has no offensive capability. It watches, detects, blocks, and learns. Nothing else.\n\n## What It Detects\n\nSENTINEL scores threats across three dimensions, backed by a learning layer:\n\n**Velocity** -- How fast is this source generating events? Humans browse. Bots spray. Fifty failed SSH logins in ten seconds is not a person.\n\n**Coverage** -- How broadly is this source probing? A legitimate user hits one endpoint. An automated scanner hits twenty ports and fifteen paths in a minute.\n\n**Correlation** -- How quickly does reconnaissance lead to exploitation? A human scans Tuesday, exploits Thursday. An AI agent discovers an open port and attempts exploitation in under a second.\n\n**Pattern Learning** -- A Hebbian graph tracks which attack phases follow which. The more attacks SENTINEL observes, the better it predicts the next step. Edges strengthen through co-occurrence and decay over time. No retraining required.\n\n## What It Does When It Detects\n\nThree things:\n\n1. **Blocks the IP** via system firewall (iptables on Linux, netsh on Windows). Disabled by default -- runs in dry-run mode until you're ready.\n2. **Alerts you** via JSONL log file, webhook (Slack, Discord, PagerDuty, Teams), or email queue (.eml files for SMTP pickup).\n3. **Learns the pattern** by strengthening Hebbian edges between observed attack phases. Next time the same progression appears, detection is faster.\n\n## Architecture\n\n```\n                    Log Files\n                   /    |    \\\n                  /     |     \\\n           auth.log  access.log  syslog\n              |        |          |\n              v        v          v\n         +---------+---------+---------+\n         | AuthLog | WebLog  | Syslog  |   Log Source Parsers\n         | Parser  | Parser  | Parser  |   (regex-based, zero-copy where possible)\n         +---------+---------+---------+\n                   \\    |    /\n                    v   v   v\n              +------------------+\n              |  LogEvent        |   Normalized event with IP, port,\n              |  (intermediate)  |   endpoint, event type, raw line\n              +------------------+\n                       |\n                       v\n              +------------------+\n              | DetectionEvent   |   Classified: AuthFailure, WebProbe,\n              | (core type)      |   ExploitAttempt, BruteForce, etc.\n              +------------------+\n                       |\n                       v\n              +------------------+\n              | Detection Engine |   Groups events by source IP into\n              |                  |   AttackSessions, runs three scorers\n              +------------------+\n               /       |       \\\n              v        v        v\n         +--------+--------+--------+\n         |Velocity|Coverage|Correlat.|  Sub-scorers (each 0.0-1.0)\n         | (0.40) | (0.35) | (0.25) |  (default weights)\n         +--------+--------+--------+\n                   \\   |   /\n                    v  v  v\n              +------------------+\n              | Threat Scorer    |   Weighted combination -\u003e ThreatScore\n              | (combined 0-1.0) |   Threshold check (default 0.7)\n              +------------------+\n                       |\n                       v\n              +------------------+\n              |  Attack Graph    |   Hebbian learning on phase transitions\n              |  (10x10 matrix)  |   MITRE-seeded, decay, persistence\n              +------------------+\n                       |\n                       v\n              +------------------+\n              | Response         |   Block IP, log alert, webhook,\n              | Orchestrator     |   email queue\n              +------------------+\n```\n\n## Quick Start\n\n```bash\n# Build\ncargo build --release\n\n# Generate default config\n./target/release/sentinel-shield init-config\n\n# Edit the config -- point to your log files\n# (see Configuration Reference below)\nvim sentinel-shield.toml\n\n# Start in dry-run mode (blocking disabled by default)\nRUST_LOG=info ./target/release/sentinel-shield start\n\n# Check status\n./target/release/sentinel-shield status\n\n# Stop\n./target/release/sentinel-shield stop\n```\n\n## Configuration Reference\n\nSENTINEL reads from `sentinel-shield.toml` (or the path you pass with `-c`). Run `init-config` to generate a default file with comments.\n\n### `[general]`\n\n| Field | Default | Description |\n|-------|---------|-------------|\n| `eval_interval_secs` | `10` | How often the engine polls for new log lines and evaluates sessions. |\n| `data_dir` | `./sentinel-data` | Where SENTINEL stores its state (graph, PID file, alerts). |\n| `graph_state_file` | `./sentinel-data/graph.json` | Path to the persisted Hebbian graph. Survives restarts. |\n\n### `[detection]`\n\n| Field | Default | Description |\n|-------|---------|-------------|\n| `threat_threshold` | `0.7` | Combined score above which an IP is considered a threat (0.0-1.0). |\n| `velocity_weight` | `0.4` | Weight for velocity in the combined score. |\n| `coverage_weight` | `0.35` | Weight for coverage in the combined score. |\n| `correlation_weight` | `0.25` | Weight for correlation in the combined score. |\n| `velocity_window_secs` | `60` | Sliding window for counting events per source. |\n| `velocity_saturation` | `100` | Events in the window at which velocity score hits 1.0. |\n| `coverage_saturation` | `20` | Unique targets (ports + endpoints) at which coverage hits 1.0. |\n| `correlation_min_gap_secs` | `1` | Recon-to-exploit gap below this scores 1.0 (instant pivot). |\n| `correlation_max_gap_secs` | `300` | Recon-to-exploit gap above this scores 0.0 (uncorrelated). |\n\nWeights should sum to 1.0. The defaults are tuned for AI attack detection: speed is the primary signal (0.4), breadth of probing is secondary (0.35), and tight recon-to-exploit timing confirms (0.25).\n\n### `[log_sources]`\n\n| Field | Default | Description |\n|-------|---------|-------------|\n| `auth_log_paths` | `[]` | Paths to auth log files. Example: `[\"/var/log/auth.log\"]` |\n| `web_log_paths` | `[]` | Paths to Apache/Nginx combined format access logs. |\n| `syslog_paths` | `[]` | Paths to syslog files. |\n\nYou can watch multiple files per source type. SENTINEL tracks byte offsets and handles log rotation.\n\n### `[response]`\n\n| Field | Default | Description |\n|-------|---------|-------------|\n| `blocking_enabled` | `false` | Whether to actually execute firewall blocks. Start with `false`. |\n| `alert_log_path` | `./sentinel-data/alerts.log` | Path to the JSONL alert log. |\n| `webhook_url` | `null` | Optional webhook URL for real-time alerts (Slack, Discord, etc.). |\n| `alert_email` | `null` | Optional email address. Writes .eml files to `{data_dir}/email_queue/`. |\n| `block_duration_secs` | `3600` | How long an IP stays blocked. `null` = permanent until manual unblock. |\n\n### `[dashboard]`\n\n| Field | Default | Description |\n|-------|---------|-------------|\n| `enabled` | `true` | Whether to start the dashboard HTTP server. |\n| `bind_address` | `127.0.0.1` | Bind address. Keep this localhost unless you know what you're doing. |\n| `port` | `8080` | Dashboard port. |\n\n**Note:** The dashboard is currently a stub. It creates the server struct but does not serve HTTP yet. The `status` CLI command is the current way to inspect state.\n\n## Learning Control\n\nThe Hebbian graph learns continuously by default. Five runtime commands let operators control that behavior without restarting the daemon.\n\n| Command | Method | What It Does |\n|---------|--------|-------------|\n| `learning_status` | GET | Returns current state: enabled/paused, rate multiplier, batch frequency. |\n| `learning_pause` | POST | Pauses learning. Detection continues unchanged -- the graph just stops updating. |\n| `learning_resume` | POST | Resumes learning from where it left off. |\n| `learning_set_rate` | POST | Sets a rate multiplier (0.0-2.0) on the Hebbian learning rate. 0.5 = half speed. 2.0 = double. Clamped at boundaries. |\n| `learning_set_batch_freq` | POST | Learn every N event batches instead of every batch. Set to 3 and the graph updates on every third batch, reducing CPU cost at the expense of granularity. Minimum 1. |\n\nThese commands are transport-agnostic. The handler layer (`src/dashboard/learning_api.rs`) accepts a command name and optional value, returns a JSON response with the operation result and current state. Wire them to HTTP, CLI, or MCP -- the handlers don't care.\n\n**When to use this:**\n\n- **Incident response** -- Pause learning during a known attack so the graph doesn't over-fit to one adversary's pattern.\n- **Tuning** -- Lower the rate multiplier while observing how the graph evolves. Raise it when you trust the input quality.\n- **Cost control** -- On high-traffic hosts, set batch frequency to 5 or 10 so the graph learns from a sample rather than every batch.\n\nDetection scoring is unaffected by these controls. Pausing learning pauses the graph, not the shield.\n\n## How Detection Works\n\n### Threat Scoring\n\nEach source IP accumulates events into an AttackSession. Every evaluation cycle, SENTINEL computes three sub-scores:\n\n**Velocity** = events_in_window / saturation_threshold, clamped to [0.0, 1.0]. A 60-second sliding window counts recent events. 100 events in a minute saturates to 1.0.\n\n**Coverage** = (unique_ports + unique_endpoints) / saturation_threshold. Twenty unique targets saturates to 1.0. An IP that hits port 22, port 80, port 443, `/admin`, `/.env`, and `/wp-login` scores higher than one that repeatedly hits port 22.\n\n**Correlation** = how quickly reconnaissance leads to exploitation from the same source. SENTINEL pairs each exploit event with the nearest preceding recon event and measures the time gap. Below 1 second scores 1.0 (instant pivot, clearly automated). Above 300 seconds scores 0.0 (uncorrelated). Linear decay between.\n\n**Combined** = (velocity * 0.4) + (coverage * 0.35) + (correlation * 0.25). If this exceeds the threat threshold (default 0.7), the source triggers a response.\n\n### Hebbian Graph\n\nSENTINEL maintains a 10x10 directed graph where nodes represent attack phases (Reconnaissance, Enumeration, VulnerabilityScan, CredentialAttack, Exploitation, PrivilegeEscalation, LateralMovement, DataExfiltration, Persistence, CommandControl).\n\nWhen two attack phases are observed from the same source within a time window, the edge between them strengthens. The Hebbian rule: `weight += learning_rate * activation_a * activation_b`.\n\nThe graph starts seeded with MITRE ATT\u0026CK common progressions (Recon -\u003e Enumeration at 2.0, VulnerabilityScan -\u003e Exploitation at 2.5, etc.) so it works from first deployment. Real observations modify these weights over time.\n\nTemporal decay (0.5% per cycle) prevents stale patterns from persisting. Edges below 0.001 are zeroed out. The graph persists to disk as JSON and survives restarts.\n\n### Kill Chain Pattern Matching\n\nTen known attack patterns are matched against each source's observed action sequence:\n\n| Pattern | Severity | Sequence |\n|---------|----------|----------|\n| Full Kill Chain (KC-001) | Critical | Recon -\u003e Enum -\u003e VulnScan -\u003e Exploit -\u003e PrivEsc -\u003e Exfil |\n| Credential Spray (CS-001) | High | Recon -\u003e Enum -\u003e CredentialAttack -\u003e Exploit |\n| Ransomware (RW-001) | Critical | Exploit -\u003e PrivEsc -\u003e Persistence -\u003e LateralMovement |\n| Lateral Movement (LM-001) | Critical | Exploit -\u003e PrivEsc -\u003e LateralMovement -\u003e C2 |\n| Data Theft via C2 (DT-001) | Critical | C2 -\u003e Exfil |\n| Automated Scanner (AS-001) | Medium | Recon -\u003e VulnScan -\u003e Enum |\n| Brute Force (BF-001) | High | Enum -\u003e CredentialAttack -\u003e CredentialAttack |\n| Persistence (SC-001) | High | Exploit -\u003e Persistence -\u003e C2 |\n| Pivot and Exfil (PE-001) | Critical | LateralMovement -\u003e Recon -\u003e PrivEsc -\u003e Exfil |\n| Initial Access Probe (IA-001) | Low | Recon -\u003e Enum |\n\nPatterns use subsequence matching with configurable minimum match counts. Partial matches are tracked as \"in progress.\"\n\n## Log Sources\n\n### auth.log\n\nParses Linux auth logs (`/var/log/auth.log`, `/var/log/secure`). Handles:\n\n- Failed password (with and without \"invalid user\")\n- Accepted password / publickey\n- Invalid user connection attempts\n- \"Too many authentication failures\" (classified as BruteForce)\n- Connection closed during auth\n- Disconnected from user\n\nString matching first, regex only for IP/port extraction. Non-matching lines cost almost nothing.\n\n### Apache/Nginx Access Logs\n\nParses combined log format. Detects:\n\n- SQL injection (UNION SELECT, OR 1=1, DROP TABLE, SLEEP, BENCHMARK, etc.)\n- Command injection (semicolon/pipe + shell commands, $(), backticks)\n- Directory traversal (../, %2e%2e, /etc/passwd, /proc/self)\n- Suspicious paths (/.env, /.git, /wp-admin, /phpmyadmin, /actuator, /server-status, etc.)\n- Scanner user agents (sqlmap, nikto, nmap, gobuster, nuclei, hydra, masscan, and 30+ more)\n\n### Syslog\n\nGeneric syslog parser. Extracts IPs from message bodies and classifies by keyword matching:\n\n- Firewall blocks (UFW, iptables, nftables) -\u003e Reconnaissance\n- Auth failure keywords -\u003e AuthFailure\n- Auth success keywords -\u003e AuthSuccess\n- Denied/refused/blocked keywords -\u003e PortProbe\n- Error/failure keywords -\u003e Suspicious\n\nSkips loopback and unspecified addresses. Lines without external IPs return nothing.\n\n## Alert Channels\n\n**JSONL File** (always active) -- One JSON object per line appended to the alert log. Each entry contains timestamp, source IP, threat score breakdown (velocity, coverage, correlation), threat level label, and reason. Parse with `jq`, `grep`, or any JSON tool.\n\n**Webhook** (optional) -- HTTP POST with JSON payload to any URL. Compatible with Slack, Discord, PagerDuty, Teams, and generic endpoints. 5-second timeout. Failures are logged but don't crash the daemon.\n\n**Email Queue** (optional) -- Writes .eml files to `{data_dir}/email_queue/`. A separate process (cron job, sendmail pickup, systemd timer) delivers them via SMTP. This avoids baking SMTP complexity into the daemon.\n\n## Defense-Only Design\n\nSENTINEL Shield cannot attack. This is not a policy decision. It is an architectural constraint.\n\nThe codebase contains:\n\n- Log parsers that read files\n- Scorers that compute numbers\n- A graph that learns edge weights\n- A blocker that adds firewall rules to DROP inbound traffic\n- Alerters that write files and POST webhooks\n\nThere is no network scanning code. No exploit generation. No payload construction. No outbound connection to target systems. The blocker uses `iptables -A INPUT ... -j DROP` and `netsh advfirewall ... action=block` -- inbound-only rules that add the IP to a deny list. The only outbound connection is the webhook POST to your own alert endpoint.\n\nThe attack patterns in the graph are detection signatures, not instructions. They describe \"if we see A then B, an attack is likely\" -- the same information published in MITRE ATT\u0026CK documentation.\n\nPrivate IPs (10.x, 172.16-31.x, 192.168.x, loopback) are never blocked to prevent accidental lockout.\n\n## Testing\n\n### Rust Tests\n\n```bash\n# Unit tests (all modules)\ncargo test\n\n# With output\ncargo test -- --nocapture\n\n# Specific module\ncargo test detection::velocity\ncargo test graph::patterns\ncargo test log_sources::auth_log\n```\n\nThe test suite includes:\n- Unit tests for each scorer, parser, and graph operation\n- Integration tests that create fake log files, feed them through the full pipeline, and verify threat scores match expectations\n- Tests for both attack scenarios (credential spray, full kill chain, web exploit) and benign traffic (should NOT trigger)\n\n### Attack Simulator\n\nA Python script that writes realistic attack log entries for end-to-end testing:\n\n```bash\n# Run all attack scenarios\npython tests/attack_simulator.py --scenario all \\\n  --auth-log /tmp/test/auth.log \\\n  --web-log /tmp/test/access.log \\\n  --syslog-path /tmp/test/syslog.log\n\n# Individual scenarios\npython tests/attack_simulator.py --scenario credential_spray --auth-log /tmp/auth.log\npython tests/attack_simulator.py --scenario web_recon_to_exploit --web-log /tmp/access.log\npython tests/attack_simulator.py --scenario full_kill_chain \\\n  --auth-log /tmp/auth.log --web-log /tmp/access.log --syslog-path /tmp/syslog.log\npython tests/attack_simulator.py --scenario benign_traffic \\\n  --auth-log /tmp/auth.log --web-log /tmp/access.log --syslog-path /tmp/syslog.log\n```\n\nUses RFC 5737 TEST-NET addresses (203.0.113.0/24 for attackers, 198.51.100.0/24 for benign traffic).\n\n## Current Status\n\n**Working:**\n- Full detection pipeline (log parsing -\u003e event classification -\u003e session scoring -\u003e response)\n- Three log source parsers (auth.log, Apache/Nginx combined, syslog)\n- Three detection dimensions (velocity, coverage, correlation)\n- Hebbian attack graph with MITRE-seeded weights, learning, decay, persistence\n- Runtime learning control (pause, resume, rate adjustment, batch frequency)\n- Ten MITRE-based kill chain patterns with subsequence matching\n- IP blocking via iptables (Linux) and netsh (Windows)\n- Alert logging (JSONL file), webhook notifications, email queue\n- CLI with start/stop/status/init-config commands\n- Graceful shutdown with state persistence\n- Session pruning and graph maintenance\n- Comprehensive test suite including integration tests and attack simulator\n\n**Stubbed:**\n- Dashboard HTTP server (struct exists, endpoints defined, `run()` returns immediately)\n- Burst velocity detection (`calculate_burst_velocity` implemented but not wired into the main scorer)\n- Weighted coverage scoring (`calculate_weighted_coverage_score` implemented but not used by default)\n- Phase correlation (`calculate_phase_correlation` implemented but not used by default)\n- `EscalateMonitoring` response type (logged, not implemented)\n\n**Planned:**\n- Dashboard with real-time session/graph visualization\n- Block expiry (automatic unblock after configured duration)\n- IPv6 support in log parsers (currently IPv4 only for auth.log and syslog extraction)\n- Systemd service file and packaging\n\n## License\n\nApache License 2.0. See [LICENSE](LICENSE).\n\n---\n\n**Made by [CIPS Corp](https://cipscorps.io)**\n\nglass@cipscorps.io | [GitHub](https://github.com/For-Sunny) | [Store](https://store.cipscorps.io)\n\nEnterprise memory infrastructure for AI systems: [CASCADE Enterprise, PyTorch Memory, Hebbian Mind, and the full CIPS Stack](https://store.cipscorps.io).\n\nCopyright (c) 2025-2026 C.I.P.S. LLC\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffor-sunny%2Fsentinel-shield","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffor-sunny%2Fsentinel-shield","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffor-sunny%2Fsentinel-shield/lists"}