Synapse is a local, workspace-centric MCP framework for operator-controlled offensive security workflows. It maintains engagement state, organizes evidence, tracks authorized scope, manages credential references, and orchestrates security tooling through controlled MCP adapters.

It gives AI agents structured assessment context so they can reason over normalized targets, services, endpoints, parameters, observations, findings, evidence, and prior actions instead of fragmented tool output.

Repository Index

Start here:

• Quick Start: install the Python environment, run setup checks, and print MCP client config.
• Example Workflow: normal passive-first assessment flow.
• Safety Model: scope, approval, credentials, evidence, and cleanup guardrails.
• Documentation: architecture, operations, reporting, adapter development, and MCP reference links.

Core project references:

• Architecture: runtime topology, data flow, and boundary decisions.
• Implementation Map: module ownership, data layout, tool surface, and schemas.
• Operations: environment setup, operator procedures, jobs, credentials, cleanup, and tests.
• Reporting Model: internal Operator / High-Level report views and what they must not imply.
• Synapse MCP: complete exposed tool list and MCP component notes.

Agent guidance:

• AGENTS.md: durable Synapse operating policy used by Codex and exposed by the Synapse MCP prompt.
• skills/: agent skills for operating and developing Synapse, grouped by runtime — skills/claude/ (synapse-ops, synapse-dev) and skills/codex/ (operate-synapse, synapse-developing). See skills/README.md for install steps.

Why Synapse Exists

Security assessments produce scattered data across Burp traffic, terminal output, OSINT services, notes, screenshots, reports, and repeated manual decisions. That fragmentation makes AI assistance brittle: an agent can miss what was already tested, forget scope, repeat noisy actions, or treat raw tool output as confirmed evidence.

Synapse provides a local operational knowledge layer for authorized work. The operator remains responsible for authorization, validation, impact assessment, and final reporting; Synapse preserves context, normalizes evidence, and makes prior assessment knowledge available through MCP tools and resources.

What Synapse Is

• An MCP framework for AI-assisted offensive security.
• A workspace and evidence layer for authorized assessments.
• A controlled orchestration layer for selected security tools.
• A local file-backed context store that agents can query.
• A project structure that can evolve with an operator's methodology.

What Synapse Is Not

• A fully autonomous pentesting agent.
• A vulnerability scanner by itself.
• A replacement for specialist tools such as Burp Suite, Nmap, FFUF, or SQLMap.
• A system intended to run active or high-impact actions without operator approval.
• A place to store secrets in notes, evidence, or reports.

Main Features

Workspace and operational memory

• Engagement-level workspaces with per-target normalized state: services, endpoints, parameters, observations, findings, actions, and evidence.
• Ingestion of Burp dumps, ffuf JSON, sitemap/crawler JSON, nmap XML, Shodan summaries, Nuclei JSONL, adapter results, and operator notes — stored as raw evidence, parsed, normalized, and deduplicated per target.
• Compact target context (workspace.prepare_target_context) so an AI client plans from what is already known instead of re-deriving it.
• Operator-reviewed finding lifecycle: candidate, confirmed, false_positive, accepted_risk, fixed, with evidence linking and report-ready export.

Scope, approval, and credential safety

• Persisted authorization scope (hosts, patterns, CIDRs) at global and workspace level; active adapters validate against the owning workspace's scope before the global file.
• Scope and execution approval are separate gates: active traffic always requires in-scope validation plus confirm=true, and adapters record consistent approval metadata.
• Scoped credentials (bearer, basic, cookie, header, browser-derived session) stored locally with 0600 permissions, redacted in every response, and resolved per request target. Browser authentication profiles (Playwright or Selenium Remote) handle SSO, MFA, and device-approval flows.
• Evidence events are sanitized for secret-bearing fields and embedded secret-bearing strings before they are written.

Passive intelligence

• Burp-like site maps and workflow graphs (JSON plus Mermaid/SVG flowcharts) from offline dumps without sending traffic.
• Rich request/response context extraction: parameters, JSON field paths, cookie names, authorization schemes, redirects, forms, API/JSON/GraphQL signals, authentication boundaries, state-changing methods, and error signals.
• Workspace fingerprinting into structured technology components with name, version, layer, confidence, and evidence sources.
• External-perimeter inventory: host assets, web applications, technology matrix, canonical login portals, protected resources, and request-aware review candidates.
• Passive candidate analyzers for SQLi, XSS, SSRF, open redirect, command injection, SSTI, LFI/RFI, SSI, access control, CSRF, CORS, XXE, GraphQL, insecure deserialization, security headers/cookies, JWT, and TLS posture.
• Passive OpenAPI/Swagger/Postman spec import that normalizes documented endpoints, parameters, and auth schemes without sending traffic.

JavaScript intelligence

• JS asset discovery from stored workspace data, approved bounded fetching, and static analysis (no JavaScript execution): API endpoints, methods, API bases, GraphQL operations, WebSocket URLs, storage keys, auth/CSRF header names, and object identifiers.
• JS-inferred endpoints normalized as derived/inferred records that never overwrite observed traffic, plus JS-enriched application maps as HTML, Markdown, or JSON.

Guarded active adapters and background jobs

• Bounded active crawling (including authenticated extended POST-form mapping), constrained ffuf and adaptive Nuclei profiles, and nmap profiles.
• Bounded, operator-approved single-shot HTTP probes for XSS, SSRF, open redirect, command injection, SSTI, LFI/RFI, SSI, XXE, CORS, and GraphQL introspection, plus approved access-control matrix replay across credential contexts. Every active probe is scope-checked, confirm=true gated, and benign by construction.
• Long-running tools run as workspace-scoped background jobs by default with durable jobs.list / jobs.status / jobs.cancel records that survive MCP restarts; lazy finalization ingests completed output into the workspace.
• The stdio transport applies bounded per-call deadlines so a slow synchronous call returns a recoverable JSON-RPC error instead of stalling the server.

Reporting and documentation

• Normalized passive report layers (perimeter, JavaScript, authentication, access control) with a shared structure: summary, sections, per-target context, coverage gaps, and recommended next steps.
• Single-layer and all-layer workspace reports as Markdown, JSON context, or portable self-contained HTML with the shared Synapse visual identity.
• Report, finding-draft, evidence-pack, coverage, and assessment-summary contexts. HTML reports are internal operator artifacts with Operator / High-Level presentation views. Report generation never sends active traffic.

Mental Model

Operator / AI client
        |
        v
MCP boundaries
|-- Burp MCP        optional live Burp Suite state and UI/session operations
`-- Synapse MCP     local policy, workspace memory, evidence, and adapters
    |-- scope and approval gates
    |-- normalized workspace entities
    |-- evidence and credential references
    |-- passive analyzers and documentation contexts
    `-- guarded active adapters with background jobs

Synapse supports two MCP boundaries:

• synapse: the local Synapse MCP for policy, state, evidence, and adapters. This is the required operational endpoint.
• burp: PortSwigger's official Burp MCP stdio proxy launcher, optional but highly recommended for live Burp Suite state and UI/session operations.

See Architecture for the full runtime topology, data flow, and boundary decisions.

Core Concepts

Concept	Purpose
Scope	Persisted authorization allowlist for hosts, patterns, and CIDRs.
Workspace	Engagement-level state under DATA/workspaces/<workspace-id>/.
Target	Per-host normalized state: services, endpoints, parameters, findings, actions, observations.
Evidence	Raw local artifacts plus global and host-indexed JSONL event logs.
Observation	A hypothesis or lead produced by parsing, passive analysis, OSINT, or workflow mapping.
Finding	Operator-reviewed or lifecycle-managed issue with status, severity, confidence, evidence IDs, impact, and remediation.
Action	Recorded passive or active tool activity for a target.
Credential	Scoped HTTP secret stored locally and referenced by credentialId; responses are redacted.
Background Job	Workspace-scoped long-running tool record polled through jobs.*.
Fingerprint	Passive technology and host-behavior summary from dumps or normalized workspace data.
Perimeter	Passive inventory of assets, technologies, web apps, login portals, protected resources, and review candidates.
Documentation Context	Structured report, finding, evidence-pack, coverage, layer, or all-workspace model built from workspace data before rendering.

Quick Start

Required:

• Python 3.10+ as python3
• A repository virtual environment for Synapse MCP runtime dependencies.
• An MCP client that can launch stdio servers, such as Codex

Recommended optional tooling:

• Playwright Chromium for browser-assisted authentication flows.
• sqlmap, ffuf, nuclei, and nmap for the matching adapter workflows.
• Java for MCPS/Burp-Mcp/mcp-proxy.jar
• Burp Suite with PortSwigger's MCP Server extension enabled
• PortSwigger's Burp MCP proxy launcher under MCPS/Burp-Mcp/

1. Create and populate the Synapse virtual environment from the repository root:

   python3 -m venv .venv
   . .venv/bin/activate
   python -m pip install -U pip
   python -m pip install -e '.[browser]'
   python -m playwright install chromium

2. Run the setup check, which validates required Synapse prerequisites and prints MCP client config:

   bin/check-setup

   Missing external scanner binaries are warnings by default because passive, offline, reporting, and static-analysis workflows still work without them.

3. For a full active-adapter workstation, require scanner binaries too:

   bin/check-setup --strict-tools

4. Print the MCP client config without running checks:

   bin/print-mcp-config

MCP clients should launch MCPS/Synapse-MCP/bin/synapse-mcp rather than a system python3, so browser-auth dependencies come from the repository venv. Both launchers source local configuration from config/synapse.env; runtime data stays under SYNAPSE_ROOT/DATA by default. Shodan API keys are never stored in config — set them only at runtime with shodan.session_key.set.

Optional Burp MCP support is not required for Synapse MCP, offline dump analysis, workspace memory, passive triage, or reports. Install it only when you need live Burp Suite state such as proxy history, Repeater, or UI/session interactions.

See Operations for environment details, timeout knobs, and the full operator procedures.

Example Workflow

1. Start an assessment workspace with authorized scope.
2. Import passive Burp traffic or run approved crawl/recon.
3. Poll any background jobs to completion with `jobs.status`.
4. Normalize endpoints, parameters, services, observations, and evidence.
5. Run or review workspace fingerprinting.
6. Refresh perimeter summary/report.
7. Prepare compact target context for an AI assistant.
8. Run deeper approved validation only when the passive picture justifies it.
9. Review candidate observations and promote validated issues into findings.
10. Link evidence and export report-ready contexts.

Example MCP tool call:

{
  "tool": "project.start",
  "arguments": {
    "organization": "Client",
    "workspaceId": "client-web-2026",
    "hosts": ["app.example.com"],
    "notes": "External web assessment scope"
  }
}

MCP Tool Surface

The authoritative runtime schemas live in MCPS/Synapse-MCP/synapse_mcp/transport/stdio_server.py; the complete, test-guarded tool list is maintained in MCPS/Synapse-MCP/README.md. At a high level, Synapse exposes tools for:

• Adapter discovery: adapters.list, adapters.capabilities.
• Project, scope, workspace, evidence, credentials, and findings lifecycle.
• Background jobs: jobs.list, jobs.status, jobs.cancel.
• Offline dumps, cache inspection, passive sitemap generation, and workflow graph artifacts.
• Workspace fingerprinting, external-perimeter analysis, and perimeter report rendering.
• JavaScript intelligence and JS-enriched app-map reports.
• Documentation contexts and internal Markdown/JSON/HTML exports.
• Web assessment adapters: crawler, ffuf, Nuclei, SQLi/XSS triage, SSRF, open redirect, command injection, SSTI, LFI/RFI, SSI, access control, CSRF, CORS, XXE, GraphQL, insecure deserialization, security headers/cookies, JWT, TLS posture, and OpenAPI/Swagger/Postman spec import.
• Infrastructure and OSINT adapters: nmap and Shodan.

Representative entity and event schemas are documented in the Implementation Map.

Adapter Framework

Synapse adapters are modular assessment components that plug into the workspace, evidence, scope, credential, action, and finding lifecycle. Each adapter declares its metadata, capabilities, risk model, traffic behavior, and output types, so organizations can build their own methodology on top of Synapse without modifying the core framework.

• Adapter Development
• Custom Adapter Template

Workspace Data Layout

Runtime data is local and file-backed under DATA/:

DATA/
|-- scope/scope.json                  global hosts, patterns, CIDRs, and notes
|-- credentials/credentials.json      scoped credential store (0600)
|-- evidence/                         global and host-indexed event logs
`-- workspaces/<workspace-id>/
    |-- workspace.json                engagement metadata and target index
    |-- scope.json                    workspace-owned scope snapshot
    |-- jobs/<job-id>/job.json        background job records
    |-- reports/                      generated layer, workspace, and app-map reports
    |-- outputs/                      workspace-level generated outputs
    `-- targets/<host>/
        |-- entities/                 services, endpoints, parameters,
        |                             findings, actions, observations
        |-- models/                   perimeter and access-control models
        |-- outputs/                  tool and JS-intelligence outputs
        `-- evidence/                 raw artifacts and Burp dumps

The full annotated layout is in the Implementation Map. Runtime data under DATA/ is ignored by git except for .gitkeep placeholders.

Safety Model

Synapse is designed for authorized security assessments and keeps the operator in control:

• Work only on systems the operator is authorized to test.
• Scope and execution approval are separate gates; active traffic requires in-scope validation and confirm=true, checked against the owning workspace's persisted scope first.
• Passive/offline ingestion may retain out-of-scope data, but it always reports scopeStatus and warnings instead of hiding authorization state.
• Credentials are scoped to authorized hosts and returned redacted; evidence events are sanitized for secrets before writing.
• Generated outputs default under workspace folders; external output paths require allowExternalOutput=true.
• Cleanup of dumps and generated artifacts is inspect-first and confirm-before-delete.
• SQLMap execution is not exposed; only offline analysis and guarded command generation are available. Command-injection execution is limited to approved benign marker requests.

The complete safety model, including credential, browser-session, and evidence-sanitization guarantees, is documented in Architecture.

Documentation

• Documentation Index
• Architecture: boundaries, data flow, safety model.
• Implementation Map: modules, tool surface, data layout, workflows, schemas.
• Reporting Model: internal report views, the presentation toggle, and what reports must not do.
• Operations: setup, operator procedures, cleanup, tests.
• Adapter Development
• Synapse MCP: complete tool list and adapter policy.
• Burp MCP notes under MCPS/Burp-Mcp/README.md when the optional launcher is installed.

Project Hygiene

• Contributing
• Security Policy
• License

Testing

Run all repository tests:

bin/test

Useful focused modes:

bin/test --core
bin/test --template
bin/test --core -k access_control

The suite covers adapter analysis, credential safety, evidence redaction, workspace ingestion and deduplication, passive Burp context parsing, candidate analyzers, JS intelligence extraction/reporting, finding lifecycle operations, active-tool ingestion hooks, MCP dispatch, and the custom adapter template.

Authorized Use Notice

Synapse is intended for authorized security testing, internal research, and defensive assessment workflows. Do not use it against systems you are not authorized to test. The operator is responsible for scope, approval, validation, and compliance with applicable laws and engagement rules.

License

Synapse is licensed under the Apache License, Version 2.0.

See LICENSE for the full license text and NOTICE for attribution and third-party notices.