# SecKit MCP

A small, auditable, **read-only** [MCP](https://modelcontextprotocol.io) server that gives an AI assistant defensive security lookup and analysis tools: check a password against known breaches without revealing it, look up a CVE, explain a MITRE ATT&CK technique, parse a log line, and defang indicators safely.

Defensive and educational only. No scanning, no exploitation, no credential testing, no telemetry, no file writes, no shell execution.

## Install

Requires Node 20+ (developed on Node 24).

```bash
git clone <this repo> seckit-mcp && cd seckit-mcp
npm install
npm run build
claude mcp add seckit -- node /absolute/path/to/seckit-mcp/dist/index.js
```

Optional: set `NVD_API_KEY` in the server environment to raise the NVD rate limit (about 5 requests per 30 s without a key).

## Tools

| Tool | Input | Output | Data source |
|---|---|---|---|
| `check_password_breach` | `password` | `{ pwned, count }` | HIBP Pwned Passwords range API (k-anonymity) |
| `lookup_cve` | `cve_id` (`CVE-YYYY-N+`) | description, CVSS v3.x score/vector/severity, dates, CWEs, affected CPEs (trimmed), top 10 references, CISA KEV flag if present | NVD CVE API 2.0 |
| `explain_mitre_technique` | `id` (`T1059`, `T1059.001`) | name, tactics, description, platforms, data sources, detection, mitigations, URL, ATT&CK version | Bundled ATT&CK snapshot (offline) |
| `search_mitre` | `query`, `limit` | ranked matches (id, name, tactics) | Bundled ATT&CK snapshot |
| `parse_log_line` | `line` (max 4 KB), `format?` | structured fields for Sysmon JSON, syslog/auth (ssh, sudo), Windows event text; `recognised: false` otherwise | Local parser |
| `defang_iocs` | `text` (max 64 KB) | defanged text plus extracted IOC list | Local |
| `refang_iocs` | `text` (max 64 KB) | live indicators plus a handling warning | Local |
| `hash_text` | `text`, `algorithm` (md5/sha1/sha256) | hex digest | Local (`node:crypto`) |
| `explain_event_id` | `event_id`, `log` (security/sysmon/system/powershell) | meaning, what to look for, related ATT&CK ids | Small bundled table |

Every result is JSON text with `source` and `retrieved_at`. Errors return `isError: true` with a short message.

Resources: `seckit://attack/tactics` (tactic list), `seckit://safety` (the safety policy). Prompt: `triage_alert` (guided what/who/where/when/scope/next-step checklist).

## Example prompts

- "What is T1003.001? Explain it and tell me what to monitor."
- "Search ATT&CK for scheduled task persistence."
- "Give me the CVSS and references for CVE-2024-3094."
- "Parse this log line: `Jan  5 10:11:12 web01 sshd[1234]: Failed password for invalid user admin from 203.0.113.7 port 51234 ssh2`"
- "What does Windows event 4625 mean, and what ATT&CK technique does it map to?"
- "Defang everything in this text so I can paste it into a ticket: ..."
- "SHA-256 of this string, please."
- "Is the string `correct-horse-battery-staple` in a known breach?" (see warning below)

## Safety and limitations

What it does: k-anonymity password check (SHA-1 is computed locally, **only the first 5 hex characters of the hash** are sent to `api.pwnedpasswords.com`, the match is local, the password is never logged, cached, echoed or put in errors); one CVE lookup per call to NVD; everything else is local.

Safeguards enforced in code and tests:
- Outbound host allow-list in `src/lib/http.ts`: exactly `api.pwnedpasswords.com` and `services.nvd.nist.gov`, https only, redirects refused. Anything else is rejected before a request is made.
- Timeouts, a descriptive User-Agent, one retry with backoff on HTTP 429, a 1-hour in-memory cache (never written to disk).
- Strict zod input validation with length limits (4 KB log lines, 64 KB IOC text, 128-char passwords).
- Text fetched from NVD is untrusted: it is returned inside a clearly labelled `untrusted_fetched_text` field and the tool descriptions say so.
- Nothing is written to stdout except MCP protocol frames (tested); no filesystem writes or shell execution in `src/` (tested statically).

Limitations (be honest about them):
- **Do not paste a real password into a chat.** The assistant and your client still see it even though the network call does not. Use a throwaway or sample string, or a client-side checker. A "not found" result does not mean a password is strong.
- The log parser and IOC extractor are heuristics. Bare-domain defanging uses a common-TLD list, and version strings like `1.2.3.4` look like IPs. Unrecognised input is flagged, not guessed.
- The ATT&CK data is a snapshot (version and generation date are in every result) and goes stale; run `npm run update-attack`.
- `explain_event_id` covers common events only and is hand-maintained.
- NVD data can lag or be incomplete; CVSS v3.x only (no v4 or EPSS).
- Detection guidance in recent ATT&CK versions (v20 in the committed snapshot) is expressed as detection strategies and analytics; the snapshot keeps the strategy names and up to four trimmed analytics each.

## ATT&CK snapshot

`src/data/attack.json` is generated from the real MITRE ATT&CK enterprise STIX bundle by `scripts/update-attack.ts` (fields kept: id, name, tactics, description, platforms, data sources, detection, mitigations, url; techniques and sub-techniques; revoked/deprecated skipped). The committed snapshot is the real generated one (version recorded in `meta.attack_version`). Regenerate with:

```bash
npm run update-attack                # downloads from mitre-attack/attack-stix-data
npm run update-attack -- ./enterprise-attack.json   # or from a local copy
```

The tools work identically against any file of the same shape (a hand-written fixture would carry `meta.fixture: true`, which is surfaced in results).

## Develop

```bash
npm test      # builds, then unit tests (mocked fetch) and end-to-end stdio tests; fully offline
npm audit
```

Layout: `src/index.ts` (wiring), `src/tools/*` (one module per tool), `src/lib/{http,ioc,logparse}.ts`, `scripts/update-attack.ts`, `tests/`.

## Data attributions

- **NVD**: CVE data from the NIST National Vulnerability Database (https://nvd.nist.gov). This product uses the NVD API but is not endorsed or certified by the NVD.
- **HIBP**: Pwned Passwords by Troy Hunt, Have I Been Pwned (https://haveibeenpwned.com/API/v3#PwnedPasswords), used via the k-anonymity range API.
- **MITRE ATT&CK**: ATT&CK(R) is a registered trademark of The MITRE Corporation. Content (c) The MITRE Corporation, reproduced under the ATT&CK Terms of Use (https://attack.mitre.org/resources/terms-of-use/).

## License

MIT, see [LICENSE](LICENSE).