Metadata-Version: 2.4
Name: blindsight
Version: 0.0.1
Summary: Agentic incident investigation framework that separates what the evidence suggests from what the data can verify.
Project-URL: Homepage, https://github.com/willstull/blindsight
Project-URL: Repository, https://github.com/willstull/blindsight
Project-URL: Issues, https://github.com/willstull/blindsight/issues
Author-email: Will Stull <willstull17@gmail.com>
License: MIT
Keywords: agentic,incident-response,investigation,llm,mcp,security
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.12
Provides-Extra: dev
Requires-Dist: duckdb<2.0.0,>=1.4.4; extra == 'dev'
Requires-Dist: mcp<2.0.0,>=1.26.0; extra == 'dev'
Requires-Dist: prompt-toolkit>=3.0.52; extra == 'dev'
Requires-Dist: pydantic-ai-slim[anthropic]<0.3.0,>=0.2.0; extra == 'dev'
Requires-Dist: pydantic<3.0.0,>=2.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: python-dotenv<2.0.0,>=1.2.2; extra == 'dev'
Requires-Dist: python-ulid<3.0.0,>=2.7.0; extra == 'dev'
Requires-Dist: pyyaml<7.0,>=6.0; extra == 'dev'
Requires-Dist: result<0.18.0,>=0.17.0; extra == 'dev'
Requires-Dist: structlog<25.0,>=24.0; extra == 'dev'
Description-Content-Type: text/markdown

# Blindsight

Coverage-aware incident investigation through MCP.

Blindsight helps incident responders answer scope, containment, and impact questions by querying existing telemetry systems in place. It normalizes evidence from multiple domains into a common model, tracks what can and cannot be verified through explicit coverage reports, and produces reproducible case records with analyst-ready reports.

## How it works

Blindsight runs bounded investigations across evidence domains (identity, application) through MCP tool interfaces. Each investigation:

1. Queries domain servers for entities, events, relationships, and coverage
2. Correlates evidence across domains in a persistent case store
3. Scores likelihood and confidence separately -- likelihood reflects the evidence pattern, confidence reflects what the available data can verify
4. Classifies coverage gaps by relevance to the specific hypothesis
5. Generates a structured incident report from the saved case

The system is read-only against upstream telemetry. It queries systems already in place rather than building a new log platform.

## Architecture

Four MCP servers:

| Server | Role |
|--------|------|
| Identity MCP | Evidence domain: account lifecycle, credentials, privilege events |
| App MCP | Evidence domain: user activity, transactions, application events |
| Investigation MCP | Orchestration: runs investigations, generates reports, follow-up queries |
| Case MCP | Persistence: DuckDB-backed case store with correlation queries |

Evidence domains are replay-backed, reading from NDJSON fixture files. The same domain contract supports live integrations without changing the investigation pipeline.

## Evaluation

Testing uses replay scenarios with known outcomes. Each scenario family includes a baseline and degraded variants (retention gaps, missing fields, missing sources) that verify the system correctly reduces confidence when evidence is incomplete.

## Documentation

See [docs/index.md](docs/index.md) for specifications, architecture decisions, and implementation details.

## Quick start

```bash
# Install dependencies
poetry install

# Run tests
poetry run pytest -q

# Run an investigation via MCP (requires .env with ANTHROPIC_API_KEY for LLM features)
# The investigation MCP server is configured in .mcp.json
```

