# https://github.com/IRsoctierDT/ai-agentic-mcpscan Project Manual

Generated at: 2026-07-12 22:24:31 UTC

## Table of Contents

- [Overview & Getting Started](#page-1)
- [Core Scanner: Host Adapters & Checks](#page-2)
- [Extended Analysis Suite](#page-3)
- [LAN Assessment, Reporting & CI Operations](#page-4)

<a id='page-1'></a>

## Overview & Getting Started

### Related Pages

Related topics: [Core Scanner: Host Adapters & Checks](#page-2), [LAN Assessment, Reporting & CI Operations](#page-4)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [README.md](https://github.com/IRsoctierDT/ai-agentic-mcpscan/blob/main/README.md)
- [pyproject.toml](https://github.com/IRsoctierDT/ai-agentic-mcpscan/blob/main/pyproject.toml)
- [src/mcpscan/__init__.py](https://github.com/IRsoctierDT/ai-agentic-mcpscan/blob/main/src/mcpscan/__init__.py)
- [src/mcpscan/cli.py](https://github.com/IRsoctierDT/ai-agentic-mcpscan/blob/main/src/mcpscan/cli.py)
- [src/mcpscan/io_safe.py](https://github.com/IRsoctierDT/ai-agentic-mcpscan/blob/main/src/mcpscan/io_safe.py)
- [src/mcpscan/redaction.py](https://github.com/IRsoctierDT/ai-agentic-mcpscan/blob/main/src/mcpscan/redaction.py)
</details>

# 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:

```bash
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:

| Command | Intent | Key release |
| --- | --- | --- |
| `mcpscan inventory` | Tier-1 AI/MCP asset inventory listing every server, tool, and scope detected across supported hosts | v1.1.0 (#49) |
| `mcpscan atlas` | Tier-2 framework mapping that groups findings against known agentic frameworks | v1.2.0 (#51) |
| `mcpscan lan` | Local-area network analysis with a Phase A safety core (authorization gate, no network egress); emits SARIF logical locations for endpoint findings | v0.8.0 → v1.3.0 (#38, #40, #53) |
| `mcpscan fix` (opt-in `--fix`) | Applies remediations for over-broad tool-scope grants | v0.5.0 (#31) |
| SARIF output (default across commands) | Code-scanning compatible 2.1.0 document with a GitHub workflow | v0.4.0 (#28) |

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:

```bash
mcpscan inventory --output report.sarif
```

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

```bash
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.

---

<a id='page-2'></a>

## Core Scanner: Host Adapters & Checks

### Related Pages

Related topics: [Overview & Getting Started](#page-1), [Extended Analysis Suite](#page-3), [LAN Assessment, Reporting & CI Operations](#page-4)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [src/mcpscan/engine.py](https://github.com/IRsoctierDT/ai-agentic-mcpscan/blob/main/src/mcpscan/engine.py)
- [src/mcpscan/adapters/__init__.py](https://github.com/IRsoctierDT/ai-agentic-mcpscan/blob/main/src/mcpscan/adapters/__init__.py)
- [src/mcpscan/adapters/base.py](https://github.com/IRsoctierDT/ai-agentic-mcpscan/blob/main/src/mcpscan/adapters/base.py)
- [src/mcpscan/adapters/claude.py](https://github.com/IRsoctierDT/ai-agentic-mcpscan/blob/main/src/mcpscan/adapters/claude.py)
- [src/mcpscan/adapters/vscode.py](https://github.com/IRsoctierDT/ai-agentic-mcpscan/blob/main/src/mcpscan/adapters/vscode.py)
- [src/mcpscan/adapters/zed.py](https://github.com/IRsoctierDT/ai-agentic-mcpscan/blob/main/src/mcpscan/adapters/zed.py)
- [src/mcpscan/checks/__init__.py](https://github.com/IRsoctierDT/ai-agentic-mcpscan/blob/main/src/mcpscan/checks/__init__.py)
- [src/mcpscan/checks/registry.py](https://github.com/IRsoctierDT/ai-agentic-mcpscan/blob/main/src/mcpscan/checks/registry.py)
- [src/mcpscan/fix.py](https://github.com/IRsoctierDT/ai-agentic-mcpscan/blob/main/src/mcpscan/fix.py)
</details>

# 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.

```mermaid
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]()

---

<a id='page-3'></a>

## Extended Analysis Suite

### Related Pages

Related topics: [Core Scanner: Host Adapters & Checks](#page-2), [LAN Assessment, Reporting & CI Operations](#page-4)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [src/mcpscan/inventory/__init__.py](https://github.com/IRsoctierDT/ai-agentic-mcpscan/blob/main/src/mcpscan/inventory/__init__.py)
- [src/mcpscan/inventory/model.py](https://github.com/IRsoctierDT/ai-agentic-mcpscan/blob/main/src/mcpscan/inventory/model.py)
- [src/mcpscan/inventory/collect.py](https://github.com/IRsoctierDT/ai-agentic-mcpscan/blob/main/src/mcpscan/inventory/collect.py)
- [src/mcpscan/inventory/classify.py](https://github.com/IRsoctierDT/ai-agentic-mcpscan/blob/main/src/mcpscan/inventory/classify.py)
- [src/mcpscan/inventory/fingerprint.py](https://github.com/IRsoctierDT/ai-agentic-mcpscan/blob/main/src/mcpscan/inventory/fingerprint.py)
- [src/mcpscan/inventory/render.py](https://github.com/IRsoctierDT/ai-agentic-mcpscan/blob/main/src/mcpscan/inventory/render.py)
- [src/mcpscan/atlas/__init__.py](https://github.com/IRsoctierDT/ai-agentic-mcpscan/blob/main/src/mcpscan/atlas/__init__.py)
- [src/mcpscan/lan/__init__.py](https://github.com/IRsoctierDT/ai-agentic-mcpscan/blob/main/src/mcpscan/lan/__init__.py)
- [src/mcpscan/lan/safety.py](https://github.com/IRsoctierDT/ai-agentic-mcpscan/blob/main/src/mcpscan/lan/safety.py)
- [src/mcpscan/adapters/vscode.py](https://github.com/IRsoctierDT/ai-agentic-mcpscan/blob/main/src/mcpscan/adapters/vscode.py)
- [src/mcpscan/adapters/zed.py](https://github.com/IRsoctierDT/ai-agentic-mcpscan/blob/main/src/mcpscan/adapters/zed.py)
- [src/mcpscan/report/sarif.py](https://github.com/IRsoctierDT/ai-agentic-mcpscan/blob/main/src/mcpscan/report/sarif.py)
- [src/mcpscan/fix/__init__.py](https://github.com/IRsoctierDT/ai-agentic-mcpscan/blob/main/src/mcpscan/fix/__init__.py)
</details>

# 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]().

---

<a id='page-4'></a>

## LAN Assessment, Reporting & CI Operations

### Related Pages

Related topics: [Overview & Getting Started](#page-1), [Core Scanner: Host Adapters & Checks](#page-2), [Extended Analysis Suite](#page-3)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [src/mcpscan/lan/__init__.py](https://github.com/IRsoctierDT/ai-agentic-mcpscan/blob/main/src/mcpscan/lan/__init__.py)
- [src/mcpscan/lan/manifest.py](https://github.com/IRsoctierDT/ai-agentic-mcpscan/blob/main/src/mcpscan/lan/manifest.py)
- [src/mcpscan/lan/verify.py](https://github.com/IRsoctierDT/ai-agentic-mcpscan/blob/main/src/mcpscan/lan/verify.py)
- [src/mcpscan/lan/scope.py](https://github.com/IRsoctierDT/ai-agentic-mcpscan/blob/main/src/mcpscan/lan/scope.py)
- [src/mcpscan/lan/budgets.py](https://github.com/IRsoctierDT/ai-agentic-mcpscan/blob/main/src/mcpscan/lan/budgets.py)
- [src/mcpscan/lan/policy.py](https://github.com/IRsoctierDT/ai-agentic-mcpscan/blob/main/src/mcpscan/lan/policy.py)
- [src/mcpscan/lan/report/sarif.py](https://github.com/IRsoctierDT/ai-agentic-mcpscan/blob/main/src/mcpscan/lan/report/sarif.py)
</details>

# 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

| Layer | Files | Guarantee |
|---|---|---|
| Entry / CLI wiring | `src/mcpscan/lan/__init__.py` | Single surface, fail-closed dispatch |
| Static assessment | `manifest.py`, `verify.py`, `scope.py`, `budgets.py`, `policy.py` | No network I/O, bounded cost |
| Reporting | `src/mcpscan/lan/report/sarif.py` | SARIF 2.1.0 with logical locations (ADR-16) |
| CI / Phase-2 ops | config anonymizer, network-lab runbook (v1.4.0) | Opt-in, audited, anonymized |

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.

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Pitfall Log

Project: IRsoctierDT/ai-agentic-mcpscan

Summary: 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
- Evidence strength: source_linked
- 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.
- Evidence: capability.host_targets | https://github.com/IRsoctierDT/ai-agentic-mcpscan

## 2. Capability evidence risk - Capability evidence risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: README/documentation is current enough for a first validation pass.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.assumptions | https://github.com/IRsoctierDT/ai-agentic-mcpscan

## 3. Maintenance risk - Maintenance risk requires verification

- Severity: medium
- Evidence strength: source_linked
- 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.
- Evidence: evidence.maintainer_signals | https://github.com/IRsoctierDT/ai-agentic-mcpscan

## 4. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- 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
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: risks.scoring_risks | https://github.com/IRsoctierDT/ai-agentic-mcpscan

## 6. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: issue_or_pr_quality=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/IRsoctierDT/ai-agentic-mcpscan

## 7. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: release_recency=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/IRsoctierDT/ai-agentic-mcpscan

<!-- canonical_name: IRsoctierDT/ai-agentic-mcpscan; human_manual_source: deepwiki_human_wiki -->