# inti-brain

An MCP server that connects your AI assistant (Claude Code / Desktop, or any
MCP client) to **Intigriti**. It pulls the programs you can access, their
scopes (domains) and rules of engagement into a local SQLite database, then
exposes tools to search programs, pull scope, and generate an actionable attack
briefing via `hack(handle)`.

It's the Intigriti equivalent of [h1-brain](https://github.com/PatrikFehrenbach/h1-brain).

> **Authorized testing only.** Use this against programs you are permitted to
> test, and follow each program's scope and rules of engagement.

## What it does

- Syncs every Intigriti program you can access (handle, name, bounty range,
  status, industry).
- Pulls each program's scope broken down by **bounty tier**, plus the rules of
  engagement — including the **required request header** (e.g.
  `X-Intigriti-Username: {you}`), safe-harbour status, and whether automated
  tooling is allowed.
- `hack(handle)` returns a full briefing: bounty-eligible assets first,
  no-bounty assets, an explicit **out-of-scope** section, the required header,
  the ROE, and (optionally) weakness-pattern hits from a disclosed-report KB.

## Requirements

- Python 3.10+
- An Intigriti **Researcher API personal access token**
  (generate at <https://app.intigriti.com/researcher/personal-access-tokens>).

## Setup

```bash
git clone https://github.com/<you>/inti-brain.git
cd inti-brain
python3 -m venv venv
./venv/bin/pip install -r requirements.txt

cp .intienv.example .intienv   # then edit .intienv with your token
```

`.intienv`:

```
INTI_USERNAME=your_intigriti_username
INTI_API_TOKEN=your_researcher_api_token
```

## Connect to Claude Code

```bash
claude mcp add inti-brain \
  -e INTI_USERNAME=your_username \
  -e INTI_API_TOKEN=your_token \
  -- /absolute/path/to/inti-brain/venv/bin/python \
     /absolute/path/to/inti-brain/server.py
```

For Claude Desktop, add an equivalent `mcpServers` entry pointing at
`venv/bin/python server.py` with the two env vars.

## First run

1. `fetch_programs` — sync every program you can access.
2. `sync_all_scopes(bounty_only=True)` — optional bulk scope pull for paying programs.
3. `hack(handle)` — full attack briefing for one program (auto-pulls fresh scope).

## Tools

| Tool | Description |
|------|-------------|
| `fetch_programs()` | Sync all accessible programs into the DB |
| `fetch_program_scope(handle)` | Fetch one program's domains + ROE |
| `sync_all_scopes(bounty_only, limit)` | Bulk scope sync (one API call each — heavy) |
| `search_programs(query, bounty_only, status, industry, min_max_bounty, limit)` | Search synced programs |
| `search_scopes(program, asset, bounty_only, asset_type, limit)` | Search scope entries |
| `get_program(handle)` | Full program detail incl. ROE + scope (auto-syncs) |
| `hack(handle)` | Attack briefing: scope by bounty tier, required header, safe-harbour/tooling flags, out-of-scope section, ROE, KB hits |
| `search_disclosed_reports(query, weakness, limit)` | Full-text pattern-KB search *(needs optional KB, below)* |
| `get_disclosed_report(id)` | Full write-up from the pattern KB *(needs optional KB)* |

## Optional: weakness-pattern KB

The two `*_disclosed_report*` tools and the "Pattern KB hits" section of
`hack()` read an optional SQLite corpus of public disclosed bug-bounty reports.
Drop a `disclosed_reports.db` into this folder (the schema from
[h1-brain](https://github.com/PatrikFehrenbach/h1-brain) works as-is), or point
`DISCLOSED_DB_FILE` at one. If absent, those tools degrade gracefully and the
rest of the server works normally.

## API

- Base: `https://api.intigriti.com/external/researcher/v1`
- Auth: `Authorization: Bearer <researcher-api-token>`
- Programs: `GET /programs?limit=&offset=` (offset pagination)
- Program detail / scope: `GET /programs/{programId}`

## Notes

- `inti_data.db`, `.intienv`, and `disclosed_reports.db` are git-ignored — your
  token and local data never get committed.
- Always send the program's required header on in-scope requests, or you risk
  being flagged / out of scope.

## License

MIT