Skip to content

About

Local MCP/AI attack-surface audit and evidence gate for authorized testing

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

270 stars

Watchers

3 watching

Forks

Latest commit

 

History

326 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

AutoRedTeam-Orchestrator

Two loops, one allowlist. The default is a local MCP/AI attack-surface audit: you point it at your own code, your AI client config, or your instruction files. It reads them, writes what it found with a file and a line, and only offers the tools your permission level allows.

The other loop is an authorized engagement. You write one target file. Humans and models share the same steps: plan, recon, detect, verify, export. A finding is confirmed only after an outside check. The same step three times in a row stops the run.

The model can decide. This program keeps the permission, the evidence, and the record.

Python License Version Status

Maturity notes · Trust boundaries · Security audits

Companion tool: AI API Key Scanner — find leaked OpenAI / Claude / Gemini / DeepSeek keys, pair each one with the relay URL beside it, and check if it still works.

Important

Beta. The supported work is reading your own project, dry-runs, and tests on systems you are allowed to touch. A setting named "sandbox" is a note in the record. It is not a container, and it is not an operating-system boundary.

In one minute

  • The default permission level is safe. It reads your project. It does not contact a target.
  • autort engage init writes a local engagement file. engage run --dry-run plans recon → detect → verify → export without touching the host. Live engage run needs scan.
  • There are four levels. Each higher level includes everything below it.
  • The model does not read the old notes in the code. It reads a short card: name, level, risk, effects, and limits.
  • The file reader parses Python. It does not import it, and it does not call the tools.
  • pip install and the container leave out the experimental engines. The git repository still has them.
flowchart LR
  files["Your code, client config, or notes"]
  reader["Read only<br/>no tool calls"]
  report["Findings<br/>file and line"]
  files --> reader --> report
Loading

The counts in this page come from the allowed list in this tree: 153 entries (143 tools, 6 prompts, 4 resources). tools/list registers resident surfaces only (registered_count: safe 21, scan 26, active-lab 27, full 27). Catalog-only tools are found with tool_search and run through detect_run / recon_run / exploit_run, or unlocked with tool_enable. Pinned SKILL.md packs are metadata only: skill_catalog / skill_read scan a local checkout and never clone or execute third-party scripts. autort capabilities profiles is the live count after a later change.

Contents

Three ways in

Same program, three doors. All three ask the same allowed list before they run a tool.

flowchart TB
  subgraph doors ["How you call it"]
    cli["autort<br/>the command line"]
    mcp["autoredteam-mcp<br/>stdio, for an editor"]
    sdk["import autort<br/>Python"]
  end
  list["Allowed list<br/>core/capability_manifest.py"]
  work["Only the tools this level permits"]
  cli --> list
  mcp --> list
  sdk --> list
  list --> work
Loading
Door Command What a first run should be
Command line autort or python -m cli.main Read your own handlers
Editor server autoredteam-mcp --stdio Start at safe
Python from autort import Scanner Search local CVE notes, or export findings you already have

Scanner and Reporter load immediately. Engagement, Exploiter, AutoPentest, and RedTeam load the first time you ask for them. Importing Scanner does not load those four.

A script that imports core directly does not pass this check. The check is the three doors above. It is also separate from the API key, from "did a person approve this", and from any container.

Start

From a checkout, typer is enough for the read-only commands.

pip install typer
python -m cli.main ai-surface scan --path handlers --format sarif -o surface.sarif
python -m cli.main ai-surface diff --baseline tests/fixtures/ai_surface/handlers.baseline.json --path handlers --ci
python -m cli.main ai-surface inventory
python -m cli.main ai-surface scan-mcp-config --path .mcp.json
python -m cli.main capabilities manifest --profile safe
python -m cli.main engage init http://127.0.0.1:3000 --profile scan
python -m cli.main engage run --dry-run

On your path:

pip install autoredteam-orchestrator
pipx install autoredteam-orchestrator
uvx --from autoredteam-orchestrator autort --help

Or from git, when the package index is behind the branch you want:

pip install "git+https://github.com/Coff0xc/AutoRedTeam-Orchestrator.git"
git clone https://github.com/Coff0xc/AutoRedTeam-Orchestrator.git
cd AutoRedTeam-Orchestrator
pip install -r requirements.txt
python -m cli.main --help

Python 3.10 or newer. Version 4.0.0 lives only in _version.py. The two commands are autort and autoredteam-mcp.

Any subcommand, including --help, prints the legal notice on stderr. --help does not ask the allowed list.

Authorized engagement

One YAML file is the session. Humans on the CLI and a model on MCP share it.

flowchart LR
  init["engage init<br/>local file"]
  plan["engage next"]
  recon["recon"]
  detect["detect"]
  verify["verify"]
  export["export"]
  init --> plan --> recon --> detect --> verify --> export
Loading
docker compose -f docker-compose.lab.yml up -d
autort engage init http://127.0.0.1:3000 --profile scan
autort engage next
autort engage run --dry-run
AUTORT_CAPABILITY_PROFILE=scan autort engage run
autort engage status

engage init, status, and next stay on safe. They write or read .autort/engage.yaml. They do not contact the target. engage run needs scan. It applies the engagement profile, allowlist, and HITL for the duration of the run, then restores the previous environment. Live engage.verify asks HITL when the engagement file sets hitl to approval or review_edit; dry-run skips that gate. A finding is confirmed only after vuln_verifier, statistical_verifier, oob_callback, or manual_review. The same execution hash more than three times stops the loop. --ci exits 2 when the loop does not pass. The run JSON includes scorecard (autort.engage.scorecard/v1) with confirmed, unconfirmed, and total. CI runs engage run --path config/engage.lab.example.yaml --dry-run --ci.

MCP tools: engage_init, engage_status, engage_next (safe), engage_run (scan). A model that only has safe can still plan the next step. Live recon needs the operator to raise the level.

The example lab is Juice Shop bound to 127.0.0.1:3000 in docker-compose.lab.yml. Copy config/engage.lab.example.yaml if you want the file without running init.

Four permission levels

The level is an argument, or the environment variable AUTORT_CAPABILITY_PROFILE, or safe when you set neither. active_lab and active-lab are the same name. Anything else is an error.

flowchart BT
  safe["safe · 30 entries<br/>read your own project"]
  scan["scan · 96 entries<br/>a system you are allowed to test"]
  lab["active-lab · 117 entries<br/>a disposable lab"]
  full["full · 153 entries<br/>you turned the rest on"]
  safe --> scan --> lab --> full
Loading

The numbers are totals, including the levels below. New catalog entries at each step: 30, then 66, then 21, then 36. tools/list stays small: 21 / 26 / 27 / 27 resident surfaces. Factory detectors, recon modules, exploit modes, and the rest of the catalog stay searchable.

Level Use it for What it adds
safe Your own checkout, on your own machine The reader, local CVE search, exporting findings, engagement plan files
scan A target the owner allowed Recon, detection, and engage run. They ship in the install, and they stay behind this level
active-lab A machine you can throw away Lab-only tools. They ask for a separate approval in the record
full The same kind of lab, with the rest switched on The experimental engines that are still in git

A second switch is the API key. AUTOREDTEAM_AUTH_MODE defaults to strict, and protected tools then need AUTOREDTEAM_API_KEY (MCP_API_KEY is the other accepted name). Issue a key with autort capabilities auth-key; the MCP wrapper enforces the manifest auth_required flag even when a handler forgot its decorator. permissive logs and allows. disabled works only when AUTOREDTEAM_ENV=test or pytest is running. Choosing full does not turn the key off.

sequenceDiagram
  participant You
  participant CLI as autort
  participant List as Allowed list
  You->>CLI: autort scan, level safe
  CLI->>List: Is port scan allowed?
  List-->>CLI: No. It needs scan.
  CLI-->>You: Stop, exit 2. Nothing was contacted.
Loading

The card the model reads

Every tool, prompt, and resource has one row in the allowed list. That row is the source of truth. A name that is not on the list stops registration. Two rows with the same kind and name fail when the list is imported.

The model used to read the notes written above each function. Those notes could describe steps the permission level was meant to withhold. At startup the server replaces both the tool description and the function notes with one card:

{name} is a {kind} in the {level} profile. Risk: {risk}. Effects: {effects}. Controls: {controls}. Use only the declared parameters. This description does not authorize a target or an action.
flowchart LR
  notes["Notes in the handler"]
  row["One row on the allowed list"]
  card["Short card stored for the model"]
  notes -.->|"not what the model reads"| card
  row --> card
Loading

Prompts return that card, the parameter names, and one line: this prompt returns the constraint and the parameters. The Python function names stay the names on the list, including plan_pentest. The name is an identifier. The text is the constraint. plan_pentest is level active-lab. This page does not show a planning procedure.

Effects are labels on the row, such as local-read, network-probe, network-active, target-write, host-exec, credential-use, persistence, offensive-content, and dry-run. The reader compares those labels with parameter names. A tool whose effects stay in the local/dry-run set and that still accepts url, host, or target is flagged as declared_effects_omit_target_contact.

What the server does at startup

mcp_stdio_server.py builds the server, reads the permission level, and asks handlers to register. Then it logs the legal notice and the auth mode. --stdio speaks over standard input. There is no cloud service and no telemetry.

flowchart TB
  start["Process starts"]
  level["Read the permission level"]
  group["Next tool group"]
  skip["This level cannot use the group<br/>do not import it"]
  own["Each tool must be on the list<br/>and owned by this group"]
  card["Write the card over the old notes"]
  reg["Register this tool"]
  once["Same server object cannot register twice"]
  start --> level --> group
  group --> skip
  group --> own --> card --> reg --> once
Loading

import handlers does not load all 22 groups. A group is imported the first time something asks for its register function. Under safe, groups that have nothing at that level stay unloaded. That is separate from what the install package leaves out.

A tool pasted into the wrong file fails. The row names the group that owns it. One file may contain a safe tool and a full tool. The full function stays an ordinary function and is not registered.

If one group cannot import, the server logs it and continues with the others. A missing optional library should not blank the reader. A tool missing from the allowed list is different: registration stops. The server should not start half-described.

The order of the 22 groups is fixed so the startup log stays stable, and so each tool is registered by the group the list names. A later group does not need an earlier group to have finished.

How a project check works

flowchart TB
  file["A Python file on disk"]
  parse["Parse the structure<br/>do not import, do not run"]
  found["Name, text, arguments, calls"]
  compare["Compare with the allowed list<br/>when the folder is handlers or the repo root"]
  out["JSON, or SARIF for GitHub code scanning"]
  file --> parse --> found --> compare --> out
Loading

Importing a handler would register tools and could pull in engines. The check has to be able to read a checkout that still contains those engines without starting them.

It understands three ways a tool can appear in source:

What you wrote Why the reader looks for it
@tool, @prompt, or @resource on a function The usual style in this repository
Tool(name=...) The lower-level MCP type, used where there is no decorator
DetectorConfig(name=...) Detector tools are built from a config. There is no function body to walk

Names are often not written as quotes. Tool(name=self.name) is common. The reader remembers simple string assignments in the file, first assignment wins, and follows a name or an attribute back to that string. A name built only at runtime stays invisible. The comparison step then reports which allowed tools the reader never saw.

Risk words are matched on word boundaries. scan matches port_scan. It does not match scanner or epoch. The text that is searched is the function name, the full decorator description, the first line of the notes, and the names the function calls. The line stored in the finding is shorter: the first line of the decorator description, or the first line of the notes.

Calls to the permission helpers themselves are ignored. A tool should not look dangerous only because it called the check.

An older shortcut is separate from that word matcher. If the only risky word is poc, and the tool name contains the letters list, search, stats, status, or query, the rating is lowered. poc_listener contains list, so it is lowered. tests/fixtures/ai_surface/labels.json locks that result. Changing the shortcut changes the default handlers scan. It is a measured change, not a cleanup.

A scan of this repository's handlers/ folder is expected to have zero auth, validator, or payload issues. session_create and engage_init are pinned for declared_effects_omit_target_contact: they store a target string locally and the card still says local-read / local-write. New issues outside that pin are a regression in the handlers or in the rules.

Client config and instruction files

flowchart LR
  json[".mcp.json, mcp.json, or claude_desktop_config.json"]
  shapes["mcpServers, or servers, or mcp.servers"]
  flags["General shell, secret-like env name, or a remote URL key"]
  json --> shapes --> flags
Loading

The reader never connects, never sends initialize, and never calls tools/list.

What it sees Why it cares
Command is powershell, pwsh, cmd, bash, sh, python, or node A general interpreter can run whatever follows. High.
An environment name matches key, token, secret, or password as a word It sees names, not secret values. monkey is not a key. api_key is. Moderate.
The object has url, serverUrl, or baseUrl A remote address is a different trust boundary from stdio. The finding records the key and the line. It does not copy the URL. Moderate.

Instruction files are markdown, text, YAML, JSON, and TOML. Lockfiles are skipped by name. In a directory, a file over 1 MB is skipped and named in the warnings. A file you named yourself is not size-capped.

--auth-mode lenient drops missing-auth issues only. It does not change the rest of the parse.

Two scans, side by side

autort ai-surface diff compares a saved JSON scan with a fresh read of the handlers. It is a command, not a tool the model can call. --ci exits 2 when a surface is added, removed, or has a changed first-line description or argument list. Leading and trailing spaces in the description are ignored. This repository pins handlers/ at tests/fixtures/ai_surface/handlers.baseline.json and runs that check in CI.

flowchart LR
  old["Saved scan JSON"]
  new["Fresh read"]
  diff["Added, removed, or changed text or arguments"]
  old --> diff
  new --> diff
Loading

Unchanged tools are left out. Parameter order alone is not a change. Each reported row is at least moderate. A saved file with no findings list warns you, then treats every current tool as added.

When a result counts

Detectors do not share one result type. Several of them set verified=True after a single echo or a syntax check. Treating that flag as proof made the check a test of whether a field was filled in.

flowchart TB
  det["A detector says verified"]
  ask{"Did an outside check say so?"}
  yes["Confirmed"]
  no["Title starts with UNCONFIRMED<br/>severity is capped"]
  det --> ask
  ask -->|"verifier, statistics, callback, or a person"| yes
  ask -->|"only the detector's own flag"| no
Loading

The outside sources are vuln_verifier, statistical_verifier, oob_callback, and manual_review. The evidence code does not import the verifier package. Verifiers pull heavier libraries, and a report still has to accept a plain dict. The caller's dict is copied. The check returns the copy.

Confidence from a number: 0.7 and above is high, 0.4 and above is medium, below that is low.

The install and the git tree

flowchart LR
  subgraph gitTree ["Git checkout"]
    reader2["Reader, list, recon, detection"]
    extra["Experimental engines<br/>still on disk"]
  end
  subgraph install ["pip install and the container"]
    published["Reader, list, command line, server, recon, detection"]
  end
  reader2 --> published
  extra -.->|"left out of the package"| published
Loading

Left out of the package: command-and-control, moving between machines, staying on a machine, post-access work, raising privilege, taking data out, hiding, credentials, Active Directory, and exploit code. They remain in git so an explicit full checkout can still import them. Deleting them would break that checkout. A second repository would split the allowed list from the code it describes.

The CI build job installs the package into a clean virtual environment. Those ten packages are not importable there. The safe list still prints. A scan of the installed handlers folder still reports no auth, validator, or payload issues. session_create and engage_init stay pinned for the effect/parameter mismatch. Importing Scanner still does not load the four lazy engines. Tests that run inside the checkout do not prove this. Those tests can still import the engines from the working tree. Package the wheel with pyproject-build. A leftover setuptools build/ directory hides python -m build.

A published install can still serve the safe reader when a handler fails to import a missing engine. That failure is logged. The other groups still register.

Repo scanners that read the git tree still see the experimental code. The package, the container, and the safe import rule do not change that.

There is no switch that picks nmap or another outside binary at scan time. Recon and detection call the Python engines in this tree. Outside-tool rows still exist on the allowed list for the levels that name them. The default scan does not shell out to them.

Detector thresholds stay where they are. There is no public accuracy test to tune them against.

Commands

Installed, the command is autort. From a checkout it is python -m cli.main.

Safe

These do not contact a target. CVE search reads the local notes.

Command You get Example
ai-surface scan Handler inventory plus MCP03/04/10 rules autort ai-surface scan --path handlers --format sarif -o surface.sarif
ai-surface inventory Local MCP client configs and skill roots, no network autort ai-surface inventory
ai-surface scan-mcp-config A read of a client config autort ai-surface scan-mcp-config --path .mcp.json
ai-surface scan-skills Named skill risks (skill.prompt_injection, secrets, downloads) autort ai-surface scan-skills --path ./skills
ai-surface diff What changed since a saved scan autort ai-surface diff --baseline tests/fixtures/ai_surface/handlers.baseline.json --path handlers --ci
capabilities profiles The four levels and their counts autort capabilities profiles
capabilities manifest One level, as data autort capabilities manifest --profile safe
tools lint A contract check of the same parse autort tools lint --path handlers
cve-search Local CVE search autort cve-search "Log4j" --severity critical --has-poc -n 20
skills catalog Pinned SKILL.md packs (URL, sha, license) autort skills catalog
skills read Scan a local checkout, then print SKILL.md if it is not critical autort skills read --path ./skills/recon
engage init Write .autort/engage.yaml and print the next step autort engage init http://127.0.0.1:3000 --profile scan
engage status Config, finding counts, next step autort engage status
engage next Next recon/detect/verify/export card autort engage next
engage run --dry-run Walk the loop without contacting the host autort engage run --dry-run --ci
version The version string autort version

autort tools is the lint group. A function of the same name still exists and is limited to the scan level, but the group occupies the command, so that function is not what autort tools runs.

Group Commands What it is
ai-surface scan, inventory, scan-mcp-config, scan-skills, diff The reader
capabilities matrix, readiness, manifest, profiles The allowed list
tools lint Contract check
skills catalog, read Pinned SKILL.md packs. Read-only
engage init, status, next, run, resume One authorized target. Plan on safe, run on scan
code-agent expand Who calls whom, from the source
runtime-api run, serve Allowlisted local audit loop, or a read-only view of a saved run
sandbox docker-smoke A record field on the run, plus local docker-smoke
ai-redteam eval-run, catalog, convert, run eval-run scores local runs. run is plan-only Internal

Higher levels

safe refuses these. The examples assume a local target you are allowed to test.

Command Level Example
engage run scan AUTORT_CAPABILITY_PROFILE=scan autort engage run
scan scan autort scan http://127.0.0.1:8000 --full
detect scan autort detect http://127.0.0.1:8000 -c sqli,xss,ssrf --format sarif
nuclei scan autort nuclei http://127.0.0.1:8000 -t cve,rce -s high,critical
report scan autort report <session-id> -f html
exploit active-lab autort exploit http://127.0.0.1:8000 --cve CVE-2021-44228
pentest full autort pentest http://127.0.0.1:8000 --phases recon,vuln_scan

exploit with neither --cve nor --auto exits 1 before the permission check.

Python

Calls are async. Most return a dict. A failure carries an "error" string. If the level is too low, the call stops before the engine is imported.

from autort import Engagement, Exploiter, Reporter
from autort import __version__  # "4.0.0"

engagement = Engagement("http://127.0.0.1:3000", profile="scan")
plan = await engagement.run(dry_run=True)

exploiter = Exploiter("http://127.0.0.1:8000")
cves = await exploiter.cve_search("Apache Log4j", severity="critical", has_poc=True)

reporter = Reporter("session_id_here")
findings = await reporter.export_findings(format="json")

Scanner needs scan. Set AUTORT_CAPABILITY_PROFILE=scan before full_recon(), port_scan(), detect_vulns(), fingerprint(), waf_detect(), subdomain_enum(), passive_recon(), or nuclei_scan().

Reporter.generate() also needs scan. Exploiter.cve_exploit(), auto_exploit(), and exploit() need active-lab or above. AutoPentest.run() and resume() need full. AutoPentest.status(session_id) stays on safe. This page does not show RedTeam calls. Those methods are full.

GitHub Action

The example sets mode on purpose. Current main defaults the Action to self-audit. The v3.1 tag still defaults to target-scan, and that mode requires a target. The tag was not moved when the default changed.

- uses: Coff0xc/[email protected]
  with:
    mode: self-audit
    path: '.'
    severity-threshold: high

The full workflow is .github/workflows/self-audit.example.yml. Output defaults to SARIF and is uploaded for code scanning. self-audit runs python -m cli.main ai-surface scan. Pass baseline to also run ai-surface diff --ci. This repository's CI pins tests/fixtures/ai_surface/handlers.baseline.json.

mode: target-scan remains for an authorized URL. It runs detection, and it needs target.

Container and client

flowchart LR
  src["Source"]
  wheel["Build the install package"]
  image["python 3.12 slim<br/>user appuser<br/>level safe"]
  cmd["Start autoredteam-mcp"]
  src --> wheel --> image --> cmd
Loading

The image does not install nmap. The same experimental trees are dropped, plus payload and wordlist material. The health check imports the server module. The image description is the package sentence: "Local MCP/AI attack-surface audit and evidence gate for authorized testing."

The server speaks stdio.

autoredteam-mcp --stdio
python -m mcp_stdio_server --stdio
{
  "mcpServers": {
    "autoredteam": {
      "command": "autoredteam-mcp",
      "args": ["--stdio"],
      "env": {
        "AUTORT_CAPABILITY_PROFILE": "safe",
        "AUTOREDTEAM_AUTH_MODE": "strict",
        "AUTOREDTEAM_API_KEY": "replace-with-a-real-key"
      }
    }
  }
}

Leave the level unset and the server stays on safe. This JSON is a valid input to the config reader. The command name autoredteam-mcp is not a general interpreter, so that part is quiet. The environment name AUTOREDTEAM_API_KEY contains key, so the reader reports it. Point the command at a wrapper, and use a name that does not look like a secret, when you want a clean config result.

Names in the code

The pictures above are the design. This section is the index: file names, counts, and the rules a change has to keep.

Allowed list, registration, and the 22 groups

The row type is Capability in core/capability_manifest.py. The index key is (kind, name).

Field Plain meaning
kind tool, prompt, or resource
name Public name. Decorator name=, or the function name
handler Which group owns it. The wrong file is refused
minimum_profile Lowest level that may register or call it
risk low, moderate, high, critical. A label, not a measurement
maturity preview, beta, experimental, restricted-experimental, internal. A label. It does not change registration
auth_required / approval_required Whether the card mentions a key and a separate approval
executor in-process (90), isolated-required (57), or external-process (6)
effects Labels joined into the card. Empty renders as none
locator Resource URI, for a resource

Current risk mix: moderate 62, critical 47, high 19, low 25. Current maturity mix: restricted-experimental 47, preview 48, beta 41, experimental 11, internal 6.

require_surface raises ProfileDenied when the level is too low. The command line turns that into exit 2. SDK methods call it before they import the engine, and before the broad except Exception that turns an engine failure into {"success": False, "error": ...}. A refused level is its own failure.

handler_enabled is true when that group owns at least one row allowed at this level. register_all_handlers runs once per server object, stored as _autort_capability_profile.

Order Module Group key Rows
1 recon_handlers recon 10
2 detector_factory detector 29
3 evidence_handlers evidence 1
4 cve_handlers cve 8
5 api_security_handlers api_security 7
6 cloud_security_handlers cloud_security 3
7 supply_chain_handlers supply_chain 3
8 redteam_handlers redteam 14
9 orchestration_handlers orchestration 12
10 lateral_handlers lateral 9
11 persistence_handlers persistence 3
12 ad_handlers ad 3
13 session_handlers session 4
14 report_handlers report 2
15 ai_handlers ai 17
16 misc_handlers misc 5
17 external_tools_handlers external_tools 8
18 parallel_handlers parallel 1
19 knowledge_handlers knowledge 3
20 mcts_handlers mcts 1
21 prompt_handlers prompts 6
22 resource_handlers resources 4

The comment at the top of handlers/__init__.py matches this table. Registration refuses a name the list does not have.

ImportError, AttributeError, and TypeError from one group are logged and the loop continues. CapabilityManifestError is re-raised. MCP 2.3 stores the description argument and returns it from list_*. Tests check that every listed description equals the card, for all four levels.

Reader rules, issues, and the comparison with the list

scan_handler_surface walks Python files and uses ast. A syntax error, an unreadable file, or a bad encoding becomes a warning. Findings sort by risk, then path, then line.

Skipped directories: .git, .hg, .svn, .venv, venv, node_modules, __pycache__, .mypy_cache, .pytest_cache, .tox, build, dist, wordlists, and symlinks. Tests are skipped unless you ask: tests/, test_*.py, *_test.py, and conftest.py.

Issues a @tool function can get:

Issue When
high_risk_tool_without_dangerous_auth High or above, and the auth decorator is below dangerous
critical_tool_without_critical_auth Critical, and the auth decorator is not critical
declared_effects_omit_target_contact Declared effects stay local or dry-run, and a parameter is named url, host, target, or another target-shaped name
target_input_without_handler_validator A target-shaped argument has no validate_inputs decorator
payload_generation_without_auth_gate The text matched payload and there is no auth decorator

Prompts and resources skip the auth and validator rows. Effect mismatch still applies when the row is local-only and the parameters include a target-shaped name.

SARIF rule ids are grouped by class, not one rule per tool: mcp_tool.auth-critical, mcp_tool.auth-missing, mcp_tool.effect-mismatch, mcp_tool.target-input, mcp_tool.factory, mcp_tool.lowlevel, mcp_prompt, mcp_resource, mcp_config, skill.prompt_injection, skill.hardcoded_secret, skill.suspicious_download_url, skill.unverifiable_remote_code, skill.missing_skill_md, surface_added, surface_removed, surface_description_changed, surface_parameters_changed.

The comparison (reconcile_capability_manifest) joins on (kind, name) when you scan the repo root or a directory named handlers.

Bucket Meaning
statically_observed A finding matches a row, and it is not a detector config
factory_accounted The match came from DetectorConfig
invisible A row had no finding. Reason: factory-generated, prompt, resource, or unseen
unlisted A finding name is not on the list. Registration would reject it

JSON stores this at summary.static_coverage. SARIF stores it at runs[].properties.static_coverage.

Diff issues are surface_added, surface_removed, surface_description_changed, and surface_parameters_changed. The join key is (kind or "tool", tool_name). A description change quotes the first 200 characters of the saved text. Rule id is the issue name. --ci fails on those four issues. Trailing spaces in the description are not a change.

core/tooling/contract.py is autort tools lint. It reuses the parse and adds duplicate names, missing annotations, a missing Args: section, and whether a high-risk tool looks able to return evidence.

Session, config, recon, and the phase machine

A target string becomes a Target with value, type (url, ip, domain, cidr, host_port), status, scheme, host, port, and path. There is no url attribute. Callers build a URL from those parts. Session storage is where a later command resumes.

Config priority is AUTORT_ environment variables, then YAML, then field defaults. AUTORT_CONFIG points at a file. Otherwise the loader looks for config/config.yaml, config/config.yml, config.yaml, and config.yml. Missing PyYAML keeps the defaults.

export_findings is safe. generate_report is scan. JSON and SARIF are the beta export path. HTML is still hardening. SARIF levels: critical and high are error, medium is warning, low and info are note.

StandardReconEngine is the --full scan. The order is init, DNS, ports, fingerprint, technology, WAF, subdomains, directories, sensitive-file notes, then a summary. The pieces are pure Python. core/engine_router.py was removed. Nothing called it.

DetectorFactory is the registry. Detectors subclass BaseDetector and implement detect. Groups on disk are access, auth, file, injection, misc, and request. A detector that marks itself verified still has to pass the outside-check rule before a report treats the finding as confirmed.

CVE search on safe reads core/cve. Sync and PoC execution are higher levels. cve_auto_exploit is active-lab.

AutoPentestOrchestrator walks recon, vuln scan, PoC execution, exploit, privilege escalation, lateral movement, exfiltrate, then report. resume(session_id) rebuilds it from the last checkpoint. The runtime fields on its config are notes the pipeline reads. They do not create a container.

Call Row on the list Level
scan without --full port_scan scan
scan --full full_recon scan
detect vuln_scan scan
nuclei nuclei_scan scan
report generate_report scan
cve-search cve_search safe
exploit --cve cve_auto_exploit active-lab
exploit --auto exploit_orchestrate active-lab
Exploiter.exploit() exploit_vulnerability active-lab
pentest auto_pentest full
pentest --resume pentest_resume full
AutoPentest.status session_status safe
engage init / status / next engage_init / engage_status / engage_next safe
engage run engage_run scan

Package exclude globs:

core.c2*  core.lateral*  core.persistence*  core.post_exploit*
core.privilege_escalation*  core.exfiltration*  core.evasion*
core.credential*  core.ad*  core.exploit*

_version and mcp_stdio_server are listed as root modules. They are not packages, and packages.find would miss them. The console script would then fail on import.

Coverage in CI measures this same install. The ten engine globs are omitted from both the run and the report, and the workflow fails under 50%. Omitting them only while collecting is not enough: a report will still show files already stored in a .coverage file. The floor is "the published install stays measured." It is not a claim that the detectors are fully covered.

core/agent_runtime is the state of a planned run: tasks, actions, a trace, and an approval marker. enforce_sandbox_policy returns a decision. execute_action_in_docker_sandbox stays a decision unless the caller passes allow_execute=True. autort sandbox docker-smoke runs a local container with the network off. A missing Docker daemon is a skip.

autort runtime-api run walks a local plan through policy and sandbox, then either skips the steps or runs the allowlisted scanners. Engage steps in that loop are dry-run unless the action sets dry_run: false and the sandbox allows network. Live recon, detect, and verify go through autort engage run. autort runtime-api serve reads /api/runs on the host and port you pass. The usual local pair is 127.0.0.1 and 8765. Neither command calls a model.

AIRedTeamRunner plans from a written scenario. Active mode raises PermissionError unless the caller passed allow_active=True. core/code_agent maps Python calls with ast and does not run the program.

The knowledge graph (kg_store, kg_query, kg_attack_paths) and plan_attack_path are full, high risk, maturity experimental. They are catalog entries. This repository does not treat them as measured planning results.

What this tree leaves undone

The reader does not open an MCP session. A live initialize / tools/list client would see the tools the server registered, which the allowed list already names, and it would have to start the server. The static comparison is the check CI can run on a checkout.

There is no proxy in front of other MCP servers.

Detector algorithms, speed, and thresholds stay where they are until an authorized benchmark exists.

The older poc plus list shortcut stays while labels.json pins it.

Tag v3.1 stays where it is. Callers who want the self-audit default set mode, or they track main.

Effect labels are checked against target-shaped parameter names at reconcile time. session_create and engage_init are the pinned mismatches.

License

MIT. See LICENSE.

Use it for authorized testing, internal review, education, and local labs. Get permission from the owner of any target. Unauthorized scanning, exploitation, persistence, exfiltration, or evasion is out of scope for this project.

About

Local MCP/AI attack-surface audit and evidence gate for authorized testing

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

270 stars

Watchers

3 watching

Forks

Releases

Packages

Contributors

Languages