SentinelForge

An evidence-led investigation agent for Windows telemetry. Start from a host and record ID; the agent queries a read-only MCP server for process lineage, network connections, behavior-specific detections, and threat-intelligence matches. It returns a prioritized case with evidence references and the exact tool-call trace.

The included planner is deterministic and adaptive: process GUIDs found in the lineage determine subsequent network and behavior queries; observed destination IPs determine intelligence lookups. It does not need an LLM or API key. Any MCP host can also use the tools directly.

Run an investigation

Requires Python 3.11 or newer:

python -m venv .venv
source .venv/bin/activate
# Windows PowerShell: .venv\Scripts\Activate.ps1
python -m pip install -e '.[dev]'
sentinel-forge --events data/events.jsonl --intel data/intel.json \
  --host LAB-WS01 --record-id 2 --output reports/investigation.md
pytest -q

The demo starts a real MCP server subprocess and talks to it over stdio. The synthetic PowerShell seed produces eight correlated events, five detection leads, a P1 priority, and twelve tool calls. The unrelated Notepad process and its connection stay outside the case. Inspect the Markdown case or full JSON evidence.

sentinel-forge --events data/events.jsonl --intel data/intel.json \
  --host LAB-WS01 --record-id 2 --format json --output reports/case.json

Related MCP server: forensic-artifact-investigator

MCP tools

Run the server independently:

sentinel-forge-server --events data/events.jsonl --intel data/intel.json

A typical MCP host configuration follows this shape; replace all paths with absolute paths on your machine:

{
  "mcpServers": {
    "sentinel-forge": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["-m", "sentinel_forge.server", "--events", "/absolute/path/to/data/events.jsonl", "--intel", "/absolute/path/to/data/intel.json"]
    }
  }
}

On Windows, point command at .venv\\Scripts\\python.exe. The server is pinned to MCP SDK 1.30.0, using its FastMCP interface. It is a stdio server; it has no HTTP listener or remote authentication configuration.

Investigation flow

flowchart TD
  A[Seed event] --> B[Host-scoped process lineage]
  B --> C[Network and behavior queries]
  C --> D[Observed destination IPs]
  D --> E[Local intelligence lookup]
  C --> F[Evidence and ATT&CK leads]
  E --> F
  F --> G[Priority and case report]

Each query is bounded. The planner has a default budget of 32 tool calls and marks a case incomplete when the budget is exhausted or results are truncated. Missing process GUIDs also produce an explicit limitation. --max-calls changes the budget. Exit code 2 marks incomplete cases; their reports are still written. Tool errors fail the investigation instead of silently producing a complete case.

Priority model

The score is the highest detector severity, plus 10 for a suspicious match in the local intelligence snapshot, capped at 100. Scores ≥85 map to P1, ≥60 to P2, and the rest to P3. The score is an investigation heuristic, not a probability of compromise. No match in the intelligence feed does not mean an indicator is safe. The supplied feed contains a clearly labeled synthetic indicator.

Work with your logs

Use the event format and export instructions. The server loads a fixed snapshot at startup; restart it after replacing the input. Process correlation uses host plus GUID rather than PID, which can be reused. The design notes describe correlation scope and limitations; detection coverage lists the ATT&CK mappings.

For interoperability with JEV, use the same event file in both projects. Select an escalated JEV record, then pass its host and record ID to SentinelForge. The projects have independent CLIs and do not require each other to be installed.

Validation and limits

Tests cover host isolation, GUID correlation, access-mask interpretation, cycle handling, query bounds, intelligence validation, missing context, budget exhaustion, MCP tool registration, and a complete client/server round trip. CI also checks lint and formatting on Python 3.11–3.13.

This version investigates exported snapshots. It does not query a live endpoint, execute response actions, or use a generative-model planner. Network evidence is limited to configured Sysmon logging. PowerShell 4104 and Security 4698 records without process GUID enrichment cannot be correlated into a process-led case. Shared ancestors can include legitimate sibling processes, and all detections need analyst validation. Production use would need indexed storage, time windows, feed freshness policies, access control, and validation against real labeled cases.

References

• MCP Python SDK

• Microsoft Sysmon

• MITRE ATT&CK

MIT license.