Metadata-Version: 2.4
Name: blindsight
Version: 0.1.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
Requires-Dist: duckdb<2.0.0,>=1.4.4
Requires-Dist: mcp<2.0.0,>=1.26.0
Requires-Dist: pydantic-ai-slim[anthropic]<0.3.0,>=0.2.0
Requires-Dist: pydantic<3.0.0,>=2.0.0
Requires-Dist: python-dotenv<2.0.0,>=1.2.2
Requires-Dist: python-ulid<3.0.0,>=2.7.0
Requires-Dist: pyyaml<7.0,>=6.0
Requires-Dist: result<0.18.0,>=0.17.0
Requires-Dist: structlog<25.0,>=24.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest>=8.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
pipx install blindsight
blindsight install
```

`blindsight install` writes the investigation MCP server into your Claude Code config (`~/.claude/settings.json` by default; pass `--project` to use `./.mcp.json` instead) and seeds `~/.blindsight/cases/` for case storage. Restart Claude Code to pick up the change.

The bundled replay scenarios are available immediately. Override the scenarios directory with `BLINDSIGHT_SCENARIOS_DIR` and the case store with `BLINDSIGHT_CASES_DIR`. LLM-driven investigations need `ANTHROPIC_API_KEY` in the environment.

CLI usage:

```bash
blindsight describe-scenario                              # list bundled scenarios
blindsight describe-scenario credential_change_baseline   # describe one
blindsight run-investigation credential_change_baseline   # run an investigation
blindsight generate-report <case-id>                      # render a Markdown report
```

## Development setup

```bash
git clone https://github.com/willstull/blindsight
cd blindsight
poetry install
poetry run pytest -q
```

The investigation MCP server is wired up in this repo's `.mcp.json` for local dev — no separate `blindsight install` step needed when working from the source tree.
