io.github.Ankit512/itsoc-mcp
Read-only MCP server over a local log-analysis backend; a client that computes no verdicts.
Open source Open in the app JSON README (API)
About
Read-only MCP server over a local log-analysis backend; a client that computes no verdicts.
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- ankit512
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.1.0
- Stars
- 1
- Last push
- 2026-09-01T03:09:01Z
- Repository state
- sumiu
- Language
- Python
- License
- MIT
- Added
- 2026-08-29 03:01:41
- Updated
- 2026-08-29 03:01:41
- Origin id
io.github.Ankit512/itsoc-mcp
README
# itsoc. — Local AI-Assisted SOC Console A **local, rules-first security operations console**. Deterministic rules detect anomalies and **own every severity verdict**; a local LLM (via Ollama) only **explains** findings in plain language — it can never set, change, or escalate a verdict. Everything runs on your machine; no logs leave it by default. > **Design principle — honesty by construction.** Every number shown is derived from real data > or reported as `n/a`. Severity comes only from the rules. MITRE tags are *derived context, not > a verdict*. Unrecognized log formats are reported as "unparsed", never a false all-clear. --- ## What it does - **Log anomaly detection** — deterministic rules (brute-force, failure→success compromise, error-burst, suspicious-port, disk pressure) over a wide range of formats: canonical `timestamp LEVEL host msg`, RFC 3164 syslog, ISO-8601 journald/rsyslog, RFC 5424, JSON-line, auth CSV (`timestamp,ip,username,status`), ManageEngine Log360 (CSV + forwarded syslog), Android logcat, Windows EVTX, Loghub envelopes, and more via the universal format layer. - **Plain-language explanations** — the local model narrates each rule-caught finding with its evidence, rule predicate, and timeline. Advisory only. - **SOC subsystems** — correlated incidents with a six-state analyst lifecycle, observed assets/users, a **Cases** board and case file (activity, observables, real attachments, eligible runbooks → pending approval only), generated/exported reports, offline STIX plus optional OEM IP lookup (`ITSOC_OEM=1`), and honest metrics. - **Live ingestion** — a UDP/TCP syslog collector streams real events into a persistent store. - **Enrichment & connectors** — offline MITRE ATT&CK mapping; optional threat-intel provider lookups and vendor (OEM) API connectors, all with user-supplied, write-only credentials. - **MCP server** — a read-only Model Context Protocol server exposes the analysis to MCP clients (Claude Desktop / Claude Code); it computes no verdicts. ### Active-scanning modules (opt-in, use with authorization) The Discovery and Vulnerabilities modules run **real nmap scans** (host discovery + NSE vuln scripts) against **private/loopback targets you own**. These are **active network operations**, not read-only — every scan is user-initiated, public targets are refused, and results are stored verbatim with source-reported severity. --- ## Quick start **Requirements:** Python 3.9+, and [Ollama](https://ollama.com/download) for local explanations. ```bash # 1. (once) pull the local model ollama pull qwen3:8b # 2. run the console python3 console/serve.py # -> opens the SOC dashboard at http://127.0.0.1:8765/ ``` Upload a log (or pick a bundled sample) and you're analyzing. The rules run in under a second; explanations fill in behind them. **The rules engine runs even without a model** — you get verdicts and evidence, with explanations honestly skipped and marked as such. Developing the React frontend (optional): ```bash python3 console/serve.py --no-open # API on :8765 cd web && npm install && npm run dev # dashboard on :5173, proxies /api → :8765 ``` --- ## Tests ```bash python3 tests/eval/run_eval.py # labeled detection eval (20/20) python3 console/test_console.py # backend + subsystems cd web && npm test # React dashboard (vitest) ``` --- ## Design constraints Data stays local (Ollama) · no model training · rules own severity, the LLM only explains · `raw` is always the real log line, never a rewrite · secrets are stored write-only and never returned to the browser · the UI never claims more than it can prove. ## License MIT — see [LICENSE](LICENSE).