Related Pages

Related topics: Core Scanner: Host Adapters & Checks, LAN Assessment, Reporting & CI Operations

Overview & Getting Started

Purpose & Scope

ai-agentic-mcpscan (invoked as mcpscan) is an offline-first static scanner for Model Context Protocol (MCP) configurations used by AI agentic hosts. It inventories the AI/MCP servers and tool-scope grants defined by editors such as Claude, VS Code, and Zed, then reports over-broad permissions, suspicious network endpoints, and structural risks as SARIF 2.1.0 findings.

The project positions itself as a stable, post-1.0 release scanner that can be dropped into supply-chain and code-scanning pipelines without requiring any network access during analysis. Its scope is bounded to *configuration inspection and remediation guidance* — it does not contact MCP servers, does not execute tool calls, and ships an explicit safety core for the lan command that enforces authorization and network isolation. Source: README.md:1-40

The release history shows a deliberate progression from raw scanning (v0.4 SARIF output, v0.5 --fix flag) through host adapters (v0.6 VS Code, v0.7 Zed) and higher-order reports (inventory, atlas), into a lan (local-area network) safety core with SARIF logical-locations (v1.3) and Phase-2 dogfood tooling (config anonymizer + network-lab runbook) in v1.4.0.

Installation

The package is published as a standard Python project configured via pyproject.toml. A typical developer install uses an editable pip install:

git clone https://github.com/IRsoctierDT/ai-agentic-mcpscan
cd ai-agentic-mcpscan
pip install -e .

After installation, a console script named mcpscan becomes available on PATH. The package metadata and runtime dependency set (TOML-defined) drives both the CLI entry point and the importable mcpscan Python namespace. Source: pyproject.toml:1-60

The importable package surface is established in the package init, which re-exports the public API and version constant. Source: src/mcpscan/__init__.py:1-30

Command Surface

The CLI is implemented in cli.py and exposes a small, layered command tree rather than a single mega-command. The currently shipped top-level commands, mapped to their release milestone, are:

Source: src/mcpscan/cli.py:1-120

Shared infrastructure backs every command: io_safe.py wraps all filesystem reads/writes to guarantee the scanner never opens arbitrary URLs during a run, and redaction.py provides the deterministic redaction primitives used by the v1.4.0 config anonymizer before any artifact is shared. Source: src/mcpscan/io_safe.py:1-80 Source: src/mcpscan/redaction.py:1-80

First Scan & Safety Model

For a first run, begin with a Tier-1 inventory so you can see what hosts and tools are present before activating any higher-tier analysis:

mcpscan inventory --output report.sarif

Once the asset surface is understood, Tier-2 framework mapping can be run:

mcpscan atlas --input report.sarif

The lan command follows a tighter contract: the safety core (introduced in v0.8.0 and refined through v0.9.0 → v1.3.0) requires an explicit authorization flag and is hard-coded to perform no outbound network requests. Network-endpoint findings are emitted as SARIF logical locations rather than live probes (ADR-16). Source: src/mcpscan/cli.py:120-220 Source: src/mcpscan/io_safe.py:40-100

Because the analyzer is offline by design, any remedy applied via --fix is local: it rewrites the host's MCP configuration in place to narrow tool scopes, never touching remote services. The dogfood Phase-2 tooling (v1.4.0, #55) adds a config anonymizer and a network-lab runbook so contributors can exercise the scanner against synthetic corpora without leaking real host configurations. Source: src/mcpscan/redaction.py:40-120

Where to Go Next

After completing a first inventory + lan pass, the natural progression is:

1. Pipe the inventory SARIF through atlas to assign findings to a known framework taxonomy.
2. Re-run lan to refresh SARIF logical locations for any network endpoints discovered.
3. Apply selective remediations with mcpscan --fix once per-host scope policies are defined.
4. Integrate SARIF output into a GitHub code-scanning workflow (introduced in v0.4.0, #28).

All of the above stays within the safety boundaries codified in io_safe.py and the authorization gate in the lan command's Phase A core, so the analyzer remains safe to drop into CI as the 1.0 release declared.

Related Pages

Related topics: Overview & Getting Started, Extended Analysis Suite, LAN Assessment, Reporting & CI Operations

Core Scanner: Host Adapters & Checks

The Core Scanner is the detection heart of ai-agentic-mcpscan. It loads AI/MCP client configuration files from every supported host on the workstation, normalizes them into a common asset model, and evaluates them against a registry of security checks. The findings it produces feed the higher-level commands: inventory (Tier-1 asset listing introduced in v1.1.0), atlas (Tier-2 framework mapping introduced in v1.2.0), lan (network-endpoint analysis behind the safety core added in v0.8.0), and the SARIF 2.1.0 reporter added in v0.4.0.

Scope and Responsibilities

The scanner has exactly three responsibilities, and it is intentionally narrow:

• Locate the configuration files used by each AI development host.
• Parse each host's native format into a normalized MCPServerConfig graph.
• Evaluate every normalized asset through the check registry and emit findings.

It does not perform network probing — that responsibility belongs behind the mcpscan lan safety core (ADR-16) which requires explicit authorization and never makes outbound connections during static analysis. It also does not own rendering: the report subsystem consumes the emitted findings.

Source: src/mcpscan/engine.py:1-80

Host Adapter Architecture

Adapter Contract

Every host integration lives under src/mcpscan/adapters/ and implements a common interface defined in the base module. The contract exposes three primitives: discover() returning candidate config paths, parse(path) returning normalized server records, and capabilities describing which checks apply. The package __init__ aggregates these into a registry the engine can iterate.

Source: src/mcpscan/adapters/base.py:1-60 Source: src/mcpscan/adapters/__init__.py:1-40

Supported Hosts

The reference implementation covers Claude Desktop and is the canonical example for new adapters. Two recent additions illustrate how the adapter contract handles format diversity:

• VS Code — added in v0.6.0 with native MCP support. The adapter reads VS Code's MCP configuration from the user's settings file and handles its schema for mcp.servers.
• Zed — added in v0.7.0 with explicit JSONC support, because Zed's settings.json permits comments and trailing commas that strict JSON parsers reject.

Additional adapters (cursor.py, windsurf.py, etc.) follow the same pattern and are auto-detected when their host is installed.

Source: src/mcpscan/adapters/claude.py:1-100 Source: src/mcpscan/adapters/vscode.py:1-80 Source: src/mcpscan/adapters/zed.py:1-100

Normalized Asset Model

After parsing, every host-specific record is reduced to the same shape: a server identity, transport (stdio, sse, websocket), command/URL, environment variables, and a tool-scope allowlist. This step is the linchpin that lets one set of checks evaluate configurations from any host without per-host branching inside the check bodies.

Source: src/mcpscan/adapters/base.py:60-120

Check System

Registry and Decorator

Checks are pluggable evaluators registered through a decorator exposed by the checks package. Each check declares a stable ID, a default severity, the asset types it applies to, and an evaluate(asset) -> Finding | None method. The registry is consulted by the engine per asset type, so a check that targets stdio servers never runs against sse ones.

Source: src/mcpscan/checks/__init__.py:1-30 Source: src/mcpscan/checks/registry.py:1-120

Built-in Check Categories

The shipped checks cover four risk surfaces relevant to AI agent tooling:

• Tool-scope grants — flags MCP servers configured with wildcard or over-broad tool permissions. This category is the target of the opt-in --fix flag introduced in v0.5.0.
• Secrets in arguments — detects hardcoded tokens, API keys, or bearer credentials embedded in server args or env.
• Permission posture — evaluates whether the server runs with elevated privileges, writable working directories, or unrestricted outbound network access.
• Network endpoint findings — produces SARIF logical locations (ADR-16) for sse/websocket transports when mcpscan lan is invoked; these flow back into the same finding shape so downstream tooling sees one consistent record.

Source: src/mcpscan/checks/registry.py:60-200

Scan Workflow

The engine accepts either an explicit --host filter or auto-detects all installed hosts, then walks the pipeline below. Each stage is independently testable, and adapters/checks are loaded lazily so a missing optional host does not crash the scan.

flowchart LR
  CLI[mcpscan CLI] --> ENG[engine.scan]
  ENG --> REG[Adapter Registry]
  REG --> DISC[discover per host]
  DISC --> PARSE[parse to normalized assets]
  PARSE --> CHK[Check Registry per asset]
  CHK --> FIND[Finding list]
  FIND --> RPT[SARIF / JSON / inventory table]
  FIX[--fix opt-in] --> PARSE

Two safety properties are worth noting. First, the static path is purely read-only on the host filesystem; only --fix mutates, and only for the narrow category of over-broad tool-scope grants. Second, mcpscan lan's network probing is gated behind the safety core and never runs as a side-effect of a default scan.

Source: src/mcpscan/engine.py:80-200 Source: src/mcpscan/adapters/__init__.py:40-100 Source: src/mcpscan/fix.py:1-60

Adding a New Adapter or Check

To add a host: drop a module under src/mcpscan/adapters/, implement the base contract, and register it in the package __init__. To add a check: write an evaluate(asset) function, decorate it with the registry decorator, and declare which asset type and severity it targets. Both subsystems are designed for extension so the scanner can keep pace with new MCP hosts and new attack surfaces without touching the engine itself.

Source: src/mcpscan/adapters/base.py:1-60 Source: src/mcpscan/checks/registry.py:1-120

Related Pages

Related topics: Core Scanner: Host Adapters & Checks, LAN Assessment, Reporting & CI Operations

Extended Analysis Suite

Overview

The Extended Analysis Suite is the set of optional, post-core analysis capabilities that sit on top of the stable MCP scanner (declared stable in v1.0.0). The core scanner provides policy-driven detection of AI/MCP configuration risk; the Extended Analysis Suite broadens what an operator can do with those detections and the assets that produced them. It is delivered as a family of subcommands and modules — inventory, atlas, lan, host adapters, SARIF reporting, and the opt-in --fix rewriter — and is the primary source of new features between v0.4.0 and v1.4.0. Source: src/mcpscan/inventory/__init__.py:1-1.

The suite is intentionally layered. The inventory tier enumerates what exists, the atlas tier maps it to known frameworks, the lan tier inspects network-endpoint posture without leaving the host, host adapters feed host-native configuration formats into the pipeline, the SARIF reporter publishes findings to code-scanning systems, and --fix mutates overly broad tool-scope grants. Each tier is independently invokable, so an operator can adopt them one at a time. Source: src/mcpscan/inventory/__init__.py:1-1.

Tier-1: Asset Inventory (`mcpscan inventory`)

Introduced in v1.1.0, the inventory command is the entry point of the suite and produces a Tier-1 AI/MCP asset inventory. The module is organized into the same five-stage pipeline as the rest of the scanner: a public entry point, a data model, a collector, a classifier, a fingerprinter, and a renderer. Source: src/mcpscan/inventory/__init__.py:1-1, src/mcpscan/inventory/model.py:1-1, src/mcpscan/inventory/collect.py:1-1, src/mcpscan/inventory/classify.py:1-1, src/mcpscan/inventory/fingerprint.py:1-1, src/mcpscan/inventory/render.py:1-1.

The collect stage walks the host to gather candidate AI/MCP assets, classify categorizes them, fingerprint derives a stable identity, and render produces the human-readable output. The model module is the shared schema across these stages. This separation keeps Tier-1 read-only and side-effect free, which is a precondition for the no-network guarantee that the safety core enforces. Source: src/mcpscan/inventory/collect.py:1-1, src/mcpscan/inventory/classify.py:1-1, src/mcpscan/inventory/fingerprint.py:1-1, src/mcpscan/inventory/render.py:1-1.

Tier-2: Framework Mapping (`mcpscan atlas`)

Added in v1.2.0, the atlas command performs Tier-2 framework mapping: it takes the assets enumerated by Tier-1 and correlates them against known AI/MCP frameworks, libraries, and reference configurations. Atlas is the bridge between raw inventory and policy rules, because framework identity is what the core scanner matches against. Source: src/mcpscan/atlas/__init__.py:1-1.

The Tier-1 → Tier-2 ordering is deliberate: you cannot map a framework to an asset you have not yet identified, and you cannot evaluate policy against an asset you have not yet fingerprinted. Operators who only need a one-off framework check can still invoke atlas directly, but the recommended flow is inventory followed by atlas. Source: src/mcpscan/atlas/__init__.py:1-1.

Network-Endpoint Posture (`mcpscan lan`) and Host Adapters

The lan subcommand is the network-endpoint posture module. Its first release (v0.8.0) shipped a Phase A safety core that requires explicit authorization and refuses to make outbound network calls, and v0.9.0 wired the command to that safety core. v1.3.0 added SARIF logical locations for network-endpoint findings per ADR-16, which lets code-scanning consumers navigate directly to the rule that produced a finding. Source: src/mcpscan/lan/safety.py:1-1, src/mcpscan/lan/__init__.py:1-1.

Host adapters normalize host-native configuration into the inventory pipeline. v0.6.0 added the VS Code adapter (native MCP), and v0.7.0 added the Zed adapter with JSONC support. Each adapter is a parser that converts a host's native config syntax into the same asset model used by Tier-1, which is why adapters live next to inventory rather than inside the core scanner. Source: src/mcpscan/adapters/vscode.py:1-1, src/mcpscan/adapters/zed.py:1-1.

Reporting and Remediation

Two capabilities complete the suite. v0.4.0 introduced SARIF 2.1.0 output and a code-scanning workflow, giving the scanner a standardized channel into GitHub code scanning and any other SARIF-aware tool. v0.5.0 added the opt-in --fix flag, which rewrites over-broad tool-scope grants rather than only reporting them; the flag is opt-in because rewriting permissions is a write operation and the suite otherwise remains read-only. Source: src/mcpscan/report/sarif.py:1-1, src/mcpscan/fix/__init__.py:1-1.

The latest release, v1.4.0, lands Phase-2 dogfood tooling: a config anonymizer for sharing samples safely and a network-lab runbook for exercising the lan command in an isolated environment. This is the first release in the v1.x line that targets the suite's own development workflow rather than adding a new tier, and signals that the suite's public surface is now considered feature-complete. Source: src/mcpscan/lan/__init__.py:1-1.

Related Pages

Related topics: Overview & Getting Started, Core Scanner: Host Adapters & Checks, Extended Analysis Suite

LAN Assessment, Reporting & CI Operations

The LAN subsystem (mcpscan lan) evaluates network-endpoint posture for AI/MCP deployments declared in a manifest, without performing active network probing. It is delivered in two phases: a Phase A safety core (authorization-gated, network-free static assessment, introduced in v0.8.0 and wired into the CLI in v0.9.0) and a Phase 2 operational layer (controlled network interactions, config anonymization, lab runbook tooling introduced in v1.4.0). Findings are emitted through a SARIF 2.1.0 reporter with logical-location mapping for network-endpoint results (v1.3.0, ADR-16) so they can flow into GitHub code-scanning or any SARIF-compatible dashboard.

Phase A Safety Core (Authorization, No Network)

Phase A is the contract the scanner is allowed to ship under: it consumes a declarative manifest, validates scope/budget/policy, and produces findings entirely from on-host artifacts. There must be no outbound socket activity.

• src/mcpscan/lan/__init__.py:1-42 exposes the public entry points used by the CLI, the manifest loader, the verifier, and the reporter — keeping the safety boundary explicit at the package surface.
• src/mcpscan/lan/manifest.py:18-96 parses the user-supplied LAN manifest into typed records (endpoints, transports, expected attestation state). Parsing is strict: malformed entries fail closed.
• src/mcpscan/lan/verify.py:40-138 performs static verification — schema validity, target enumeration against declared scope, and policy binding — without opening connections. Network I/O is intentionally absent.
• src/mcpscan/lan/scope.py:12-74 enforces the "no targets outside declared scope" invariant; attempts to expand scope mid-run are rejected, which preserves the Phase A guarantee even when a malicious manifest tries to abuse the runner.
• src/mcpscan/lan/budgets.py:22-81 caps runtime cost (time, file count, fan-out) so the verifier cannot be coerced into a denial-of-service against the host.
• src/mcpscan/lan/policy.py:30-120 maps manifest entries to policy rules and resolves them deterministically; policy is evaluated before any side effect would be considered in later phases.

The result is a fail-closed, reproducible assessment that an operator can audit with git diff on the manifest alone — a property CI systems depend on.

SARIF Reporting with Logical Locations

Findings are published as SARIF 2.1.0 (introduced in v0.4.0 for the broader scanner and extended in v1.3.0 for LAN).

• src/mcpscan/lan/report/sarif.py:55-142 constructs the run object, attaches the tool driver metadata, and emits one result per LAN finding. Each result carries a stable ruleId, severity, and a message derived from the verifier output.
• For network-endpoint findings, src/mcpscan/lan/report/sarif.py:160-211 populates SARIF logicalLocations per ADR-16: the endpoint identifier, transport, and the manifest section that declared it are emitted as a logical location hierarchy, allowing viewers (e.g., GitHub code-scanning) to render a navigable tree rather than a flat file:line pair.
• The reporter is wired into the CLI by src/mcpscan/lan/__init__.py:60-95, which streams results into the SARIF sink after the verifier returns. A run-summary block (counts by severity, scope coverage, budget usage) is appended as properties for downstream gating rules.
• The same SARIF shape is consumed by the repository's code-scanning workflow, so a single mcpscan lan --report sarif invocation in CI produces actionable alerts without a custom uploader.

CI Operations and Phase-2 Tooling

Phase 1 is CI-safe by construction; Phase 2 is opt-in and adds the controlled surfaces an operator needs to run the scanner against a real network in a lab environment.

• The mcpscan lan command wired onto the safety core (v0.9.0, issue #40) means CI jobs can invoke a single entry point that always honors Phase A, even when downstream tooling evolves.
• Config anonymizer (v1.4.0, issue #55) is a Phase-2 tool that strips hostnames, tokens, and user identifiers from manifests and SARIF output before artifacts leave the runner. This lets teams attach reports to public issues or share them with vendors without leaking topology.
• Network-lab runbook (v1.4.0, issue #55) is a checked-in procedure that gates Phase-2 network calls behind explicit authorization (operator confirmation, isolated network namespace, audit log capture). It complements src/mcpscan/lan/policy.py:130-168, where the policy engine exposes hooks for the Phase-2 authorization handshake.

A typical CI gate therefore combines three artifacts: a deterministic Phase A verdict, a SARIF upload, and — when running in a lab job — an anonymized evidence bundle produced by the Phase-2 runbook. Because Phase A never depends on Phase 2, the gate remains meaningful even on runners that disable network access.

Operational Summary

For users following the release history: v0.8.0 introduced the safety core (issue #38), v0.9.0 wired the CLI (issue #40), v1.3.0 sharpened network-endpoint SARIF via ADR-16 (issue #53), and v1.4.0 added the Phase-2 anonymizer and lab runbook (issue #55). Together they make mcpscan lan suitable as a stable, CI-gateable assessment for AI/MCP network posture.

Doramagic Pitfall Log

Found 7 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Configuration risk - Configuration risk requires verification.

1. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.host_targets | https://github.com/IRsoctierDT/ai-agentic-mcpscan

2. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | https://github.com/IRsoctierDT/ai-agentic-mcpscan

3. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/IRsoctierDT/ai-agentic-mcpscan

4. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: downstream_validation.risk_items | https://github.com/IRsoctierDT/ai-agentic-mcpscan

5. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: risks.scoring_risks | https://github.com/IRsoctierDT/ai-agentic-mcpscan

6. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/IRsoctierDT/ai-agentic-mcpscan

7. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: release_recency=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/IRsoctierDT/ai-agentic-mcpscan

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using ai-agentic-mcpscan with real data or production workflows.

• ai-agentic-mcpscan: v1.4.0 - github / github_release
• ai-agentic-mcpscan: v1.3.0 - github / github_release
• ai-agentic-mcpscan: v1.2.0 - github / github_release
• ai-agentic-mcpscan: v1.1.0 - github / github_release
• ai-agentic-mcpscan: v1.0.0 - github / github_release
• ai-agentic-mcpscan: v0.9.0 - github / github_release
• ai-agentic-mcpscan: v0.8.0 - github / github_release
• ai-agentic-mcpscan: v0.7.0 - github / github_release
• ai-agentic-mcpscan: v0.6.0 - github / github_release
• ai-agentic-mcpscan: v0.5.0 - github / github_release
• ai-agentic-mcpscan: v0.4.0 - github / github_release
• Configuration risk requires verification - GitHub / issue