{
  "markdown": "# itsoc. — Local AI-Assisted SOC Console\n\nA **local, rules-first security operations console**. Deterministic rules detect anomalies and\n**own every severity verdict**; a local LLM (via Ollama) only **explains** findings in plain\nlanguage — it can never set, change, or escalate a verdict. Everything runs on your machine;\nno logs leave it by default.\n\n> **Design principle — honesty by construction.** Every number shown is derived from real data\n> or reported as `n/a`. Severity comes only from the rules. MITRE tags are *derived context, not\n> a verdict*. Unrecognized log formats are reported as \"unparsed\", never a false all-clear.\n\n---\n\n## What it does\n\n- **Log anomaly detection** — deterministic rules (brute-force, failure→success compromise,\n  error-burst, suspicious-port, disk pressure) over a wide range of formats: canonical\n  `timestamp LEVEL host msg`, RFC 3164 syslog, ISO-8601 journald/rsyslog, RFC 5424, JSON-line,\n  auth CSV (`timestamp,ip,username,status`), ManageEngine Log360 (CSV + forwarded syslog),\n  Android logcat, Windows EVTX, Loghub envelopes, and more via the universal format layer.\n- **Plain-language explanations** — the local model narrates each rule-caught finding with its\n  evidence, rule predicate, and timeline. Advisory only.\n- **SOC subsystems** — correlated incidents with a six-state analyst lifecycle, observed\n  assets/users, a **Cases** board and case file (activity, observables, real attachments,\n  eligible runbooks → pending approval only), generated/exported reports, offline STIX plus\n  optional OEM IP lookup (`ITSOC_OEM=1`), and honest metrics.\n- **Live ingestion** — a UDP/TCP syslog collector streams real events into a persistent store.\n- **Enrichment & connectors** — offline MITRE ATT&CK mapping; optional threat-intel provider\n  lookups and vendor (OEM) API connectors, all with user-supplied, write-only credentials.\n- **MCP server** — a read-only Model Context Protocol server exposes the analysis to MCP clients\n  (Claude Desktop / Claude Code); it computes no verdicts.\n\n### Active-scanning modules (opt-in, use with authorization)\n\nThe Discovery and Vulnerabilities modules run **real nmap scans** (host discovery + NSE vuln\nscripts) against **private/loopback targets you own**. These are **active network operations**,\nnot read-only — every scan is user-initiated, public targets are refused, and results are stored\nverbatim with source-reported severity.\n\n---\n\n## Quick start\n\n**Requirements:** Python 3.9+, and [Ollama](https://ollama.com/download) for local explanations.\n\n```bash\n# 1. (once) pull the local model\nollama pull qwen3:8b\n\n# 2. run the console\npython3 console/serve.py\n# -> opens the SOC dashboard at http://127.0.0.1:8765/\n```\n\nUpload a log (or pick a bundled sample) and you're analyzing. The rules run in under a second;\nexplanations fill in behind them. **The rules engine runs even without a model** — you get\nverdicts and evidence, with explanations honestly skipped and marked as such.\n\nDeveloping the React frontend (optional):\n```bash\npython3 console/serve.py --no-open      # API on :8765\ncd web && npm install && npm run dev     # dashboard on :5173, proxies /api → :8765\n```\n\n---\n\n## Tests\n\n```bash\npython3 tests/eval/run_eval.py        # labeled detection eval (20/20)\npython3 console/test_console.py       # backend + subsystems\ncd web && npm test                    # React dashboard (vitest)\n```\n\n---\n\n## Design constraints\n\nData stays local (Ollama) · no model training · rules own severity, the LLM only explains ·\n`raw` is always the real log line, never a rewrite · secrets are stored write-only and never\nreturned to the browser · the UI never claims more than it can prove.\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n",
  "bytes": 3724,
  "sha": "8d1bbf2bea810320f3e91ab27235e091c913e6cbad43d41693d71b1ee187ce8a",
  "repo_slug": "ankit512/log-anomaly-detector",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_ankit512_itsoc_mcp_dde04637/readme"
}