awarexone · shuvonsec · Sep 17, 2026 · Sep 16, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -10,15 +10,20 @@
 | Doing | Command / skill |
 |---|---|
 | Full audit | `/axguard-audit` or skill `axguard-audit` |
+| MCP-first review / investigate / verify fix | skill `axguard-security` → [docs/mcp.md](docs/mcp.md) |
 | Security lead pass | skill `axguard-cso` |
 | Triage | `/axguard-triage` |
 | Fix | `/axguard-fix` / skill `axguard-remediate` |
 | Report | `/axguard-report` |
 
+`axguard-security` teaches when to call AXGuard and which MCP tool to use (`axguard_security_review`, `axguard_investigate`, `axguard_verify_fix`). Prefer MCP when available; CLI as fallback.
+
 CLI:
 
 ```bash
 pip install -e .
+pip install -e '.[mcp]'   # agent MCP interface
 axguard help
 axguard audit .
+axguard mcp doctor
 ```
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -19,6 +19,7 @@ pip install -e .
 | What you are doing | Start here |
 |---|---|
 | About to publish | `/axguard-audit` |
+| Security Diff on a change | `/axguard-diff` · `axguard diff` |
 | Quick check while coding | `/axguard-scan` |
 | New / unknown codebase | `/axguard-threat-model` → `/axguard-audit` |
 | Secrets | `/axguard-secrets` |
@@ -46,8 +47,11 @@ threat-model → audit → triage → fix → report → ci
 | Skill | Role |
 |---|---|
 | `axguard-audit` | Pre-ship Lead — full A→Z |
+| `axguard-security` | MCP-first agent security skill (when to call / which tool / how to read verdicts) |
 | `axguard-cso` | Chief Security Officer — confidence-gated lead pass |
 | `axguard-preship` | Focused checklist |
 | `axguard-triage` | False-positive filter |
 | `axguard-remediate` | Patch + re-audit |
 | `axguard-report` | HTML/MD deliverables |
+
+MCP (AI coding agents): `pip install -e '.[mcp]'` → `axguard mcp` · skill `axguard-security` · [docs/mcp.md](docs/mcp.md)
diff --git a/README.md b/README.md
@@ -43,6 +43,21 @@ Pre-ship security gate — not a full pentest platform. Scan source, triage nois
 
 ---
 
+## Pre-Ship Security
+
+Find → Explain → Fix → Verify → Ship.
+
+```bash
+axguard preship .
+```
+
+AXGuard analyzes security-sensitive changes, verifies findings, checks attack paths and security regressions, and tells you whether the application is ready to ship.
+
+- Pre-Ship: [docs/preship.md](docs/preship.md)
+- Security Diff: [docs/security-diff.md](docs/security-diff.md)
+
+---
+
 ## What is AXguard?
 
 **AXguard is a pre-ship security gate.**
@@ -73,6 +88,8 @@ Use AXGuard as the security layer for your coding agent.
 ```text
 AI Agent
    ↓
+AXGuard Agent Skill
+   ↓
 AXGuard MCP
    ↓
 AXGuard Security Engine
@@ -88,7 +105,13 @@ Agent Skills
 GitHub
 ```
 
-Primary agent tool: `axguard_security_review`. Install: `pip install -e '.[mcp]'` → `axguard mcp doctor` → configure your host ([docs/mcp-config.md](docs/mcp-config.md)). Overview: [docs/mcp.md](docs/mcp.md) · Tools: [docs/mcp-tools.md](docs/mcp-tools.md) · Security: [docs/mcp-security.md](docs/mcp-security.md).
+| Layer | Role |
+|---|---|
+| **CLI** | Human security interface |
+| **MCP** | AI-agent security interface (`axguard mcp`) |
+| **Agent Skill** | Teaches agents *when* to use AXGuard (`skills/axguard-security`) |
+
+Primary agent tool: `axguard_security_review`. After a fix: `axguard_verify_fix`. Install: `pip install -e '.[mcp]'` → `axguard mcp doctor` → configure your host ([docs/mcp-config.md](docs/mcp-config.md)). Overview: [docs/mcp.md](docs/mcp.md) · Tools: [docs/mcp-tools.md](docs/mcp-tools.md) · Security: [docs/mcp-security.md](docs/mcp-security.md) · Skill roadmap: [docs/mcp-skill-roadmap.md](docs/mcp-skill-roadmap.md).
 
 ---
 
@@ -222,6 +245,8 @@ open .findings/axguard/axguard-report.html
 | Security Memory | `axguard memory record .` → [docs/memory](docs/memory/README.md) |
 | Investigation Agent | `axguard investigate .` → [docs/investigation](docs/investigation/README.md) |
 | Predictive security risk | `axguard predict .` → [docs/predictive](docs/predictive/README.md) |
+| Security Diff | `axguard diff` → [docs/security-diff.md](docs/security-diff.md) |
+| Pre-Ship gate | `axguard preship .` → [docs/preship.md](docs/preship.md) |
 | Local Security Intelligence API | `axguard api start` → [docs/api](docs/api/overview.md) |
 | MCP for AI coding agents | `axguard mcp` → [docs/mcp.md](docs/mcp.md) |
 | GitHub PR bot (self-host) | `axguard github setup` → [docs/github](docs/github/README.md) |
@@ -357,6 +382,16 @@ axguard predict --agent
 axguard predict --mcp
 axguard predict --what-if
 
+# Security Diff (security-aware comparison of two versions)
+axguard diff
+axguard diff HEAD~1
+axguard diff main...HEAD
+axguard diff --base main --head HEAD
+axguard diff --json
+axguard diff --verbose
+axguard diff --fail-on high
+axguard diff baseline save
+
 # Training-data pipeline (no model training)
 axguard data discover
 axguard data inspect

diff --git a/docs/mcp-skill-roadmap.md b/docs/mcp-skill-roadmap.md
@@ -1,14 +1,14 @@
 # AXGuard MCP → Agent Skill Roadmap
 
 **Date:** 2026-09-17  
-**Status:** Foundation only — **not** a full Agent Skill implementation.  
-**Related:** [mcp-research.md](./mcp-research.md), [mcp-threat-model.md](./mcp-threat-model.md)
+**Status:** Skill implemented — `skills/axguard-security/` (behavioral wrapper over MCP; no duplicated engines).  
+**Related:** [mcp-research.md](./mcp-research.md), [mcp-threat-model.md](./mcp-threat-model.md), [mcp.md](./mcp.md)
 
 ---
 
 ## Purpose
 
-Document how a future **AXGuard Agent Skill** should sit **above** MCP without duplicating security logic, tool schemas, or finding/evidence formats.
+Document how the **AXGuard Agent Skill** sits **above** MCP without duplicating security logic, tool schemas, or finding/evidence formats.
 
 ```text
 Agent Skill          ← teaches when/how to use AXGuard
@@ -22,23 +22,25 @@ Do **not** implement the Skill as a replacement for MCP.
 
 ---
 
-## Future skill YAML (from product brief)
+## Skill package
 
 ```yaml
 name: axguard-security
-description: Scan applications for security vulnerabilities, investigate findings, and help verify fixes before deployment.
+description: Analyze code for security vulnerabilities, investigate findings, verify fixes, and assess security risk before deployment.
 ```
 
-The skill should instruct the agent roughly:
+Path: `skills/axguard-security/SKILL.md`
+
+The skill instructs:
 
 ```text
 Before shipping security-sensitive code:
-1. Use AXGuard security review.
+1. Use AXGuard security review (MCP).
 2. Investigate suspicious findings.
 3. Review evidence and counter-evidence.
 4. Check attack paths and regressions.
 5. Separate verified findings from predictive risk.
-6. Verify fixes before declaring an issue resolved.
+6. Verify fixes with axguard_verify_fix before declaring resolved.
 ```
 
 ---
@@ -51,7 +53,7 @@ Before shipping security-sensitive code:
 | **MCP** | Tool/resource/prompt surface; structured outputs; policy gates; path/network limits | Host-agent pedagogy beyond tool descriptions |
 | **Core** | All security reasoning | Client-specific UX copy |
 
-Reuse MCP tool names (`axguard_security_review`, `axguard_investigate`, …) and schemas so the Skill is a thin behavioral wrapper.
+Reuse MCP tool names (`axguard_security_review`, `axguard_investigate`, `axguard_verify_fix`, …) and schemas so the Skill is a thin behavioral wrapper.
 
 ---
 
@@ -86,8 +88,8 @@ MCP
 
 | Phase | Deliverable | Notes |
 |---|---|---|
-| **Now** | Native MCP server (stdio), `axguard_security_review`, policy, docs | This initiative |
-| **Next** | Agent Skill package (`axguard-security`) wrapping MCP tools | No duplicated engines; YAML + playbook only |
+| **Done** | Native MCP server (stdio), `axguard_security_review`, policy, docs | PR #22 |
+| **Done** | Agent Skill (`axguard-security`) + `axguard_verify_fix` | This initiative |
 | **Later** | GitHub Actions invoking the same core/API | MCP stays independent of GitHub |
 | **Later** | GitHub Security Review / App comments & checks | Reuse review engine; do not couple MCP transport to GitHub |
 
@@ -112,11 +114,4 @@ All converge on the **same** AXGuard security engine.
 2. Keep MCP output free of marketing; Skill may add human-facing onboarding separately.
 3. Local-first: Skill install must not require AwareXone cloud.
 4. Prefer teaching agents to call `axguard_security_review` before inventing ad-hoc scanner chains.
-
----
-
-## Non-goals (this document)
-
-- Full `SKILL.md` body or installer
-- Shipping Skill files under `skills/` in this pass
-- GitHub App / Actions implementation
+5. Prefer `axguard_verify_fix` after remediations — never resolve on path rename alone.
diff --git a/docs/mcp-tools.md b/docs/mcp-tools.md
@@ -73,9 +73,12 @@ Does **not** modify source, execute exploits, or treat predictive risk as a veri
 | `axguard_list_findings` | AUTO | RO, idempotent | Summaries after scan/review. Use progressive disclosure. |
 | `axguard_get_finding` | AUTO | RO, idempotent | One finding: severity, confidence, location, verdict. |
 | `axguard_verify_finding` | AUTO / APPROVAL_REQUIRED (deep) | RO, idempotent | Hunter→Judge style verification for a candidate. |
+| `axguard_verify_fix` | APPROVAL_REQUIRED | RO | After a fix: re-scan and return `RESOLVED` / `STILL_PRESENT` / `REGRESSED` by fingerprint. Never resolve on path rename alone. |
 
 Verdicts remain AXGuard-owned (`VERIFIED` · `LIKELY` · `UNVERIFIED` · `FALSE_POSITIVE` · `REQUIRES_REVIEW`). Agents must not “declare vulnerable” without this evidence path.
 
+**Agent Skill:** prefer MCP tools via `skills/axguard-security` rather than inventing scan chains.
+
 ---
 
 ## Evidence

diff --git a/docs/mcp.md b/docs/mcp.md
@@ -76,12 +76,30 @@ Typical agent result shape: decision, risk, verified findings, evidence, attack
 | Possible vulnerability to dig into | `axguard_investigate` |
 | Authz / agent / MCP permission changes | `axguard_security_review` |
 | “What attack paths does this create?” | `axguard_find_attack_paths` / review |
-| Fix applied — confirm resolved | `axguard_security_review` or `axguard_verify_finding` |
+| Fix applied — confirm resolved | `axguard_verify_fix` (never mark resolved on file edit alone) |
 
 Full catalog and approval tiers: [mcp-tools.md](mcp-tools.md).
 
 ---
 
+## Agent Skill
+
+The behavioral layer above MCP (no duplicated scanners):
+
+```text
+AI Coding Agent
+      ↓
+AXGuard Agent Skill (`skills/axguard-security`)
+      ↓
+AXGuard MCP
+      ↓
+AXGuard Security Engine
+```
+
+Skill teaches **when** to call AXGuard, **which** tool, and **how** to interpret VERIFIED / UNKNOWN / FALSE_POSITIVE / PREDICTIVE_RISK. Install via `./install.sh --agent agents` (or Cursor/Claude skill install). Roadmap: [mcp-skill-roadmap.md](mcp-skill-roadmap.md).
+
+---
+
 ## Quick start
 
 ```bash

diff --git a/engines/mcp/policy.py b/engines/mcp/policy.py
@@ -33,6 +33,7 @@ class ApprovalTier(str, Enum):
     "axguard_list_findings": ApprovalTier.AUTO,
     "axguard_get_finding": ApprovalTier.AUTO,
     "axguard_verify_finding": ApprovalTier.APPROVAL_REQUIRED,
+    "axguard_verify_fix": ApprovalTier.APPROVAL_REQUIRED,
     # Evidence
     "axguard_get_evidence": ApprovalTier.AUTO,
     "axguard_get_evidence_chain": ApprovalTier.AUTO,

diff --git a/engines/mcp/server.py b/engines/mcp/server.py
@@ -244,6 +244,20 @@ def axguard_get_finding(finding_id: str, approved: bool = False) -> dict[str, An
     def axguard_verify_finding(finding_id: str | None = None, approved: bool = False) -> dict[str, Any]:
         return wrap_fn(HANDLERS["axguard_verify_finding"])(finding_id=finding_id, approved=approved)
 
+    @mcp.tool(name="axguard_verify_fix", description=by_name["axguard_verify_fix"]["description"], annotations=ann_fn("axguard_verify_fix"))
+    def axguard_verify_fix(
+        finding_id: str | None = None,
+        fingerprint: str | None = None,
+        path: str | None = None,
+        approved: bool = False,
+    ) -> dict[str, Any]:
+        return wrap_fn(HANDLERS["axguard_verify_fix"])(
+            finding_id=finding_id,
+            fingerprint=fingerprint,
+            path=path,
+            approved=approved,
+        )
+
     @mcp.tool(name="axguard_get_evidence", description=by_name["axguard_get_evidence"]["description"], annotations=ann_fn("axguard_get_evidence"))
     def axguard_get_evidence(finding_id: str | None = None, approved: bool = False) -> dict[str, Any]:
         return wrap_fn(HANDLERS["axguard_get_evidence"])(finding_id=finding_id, approved=approved)

diff --git a/engines/mcp/tools/catalog.py b/engines/mcp/tools/catalog.py
@@ -199,6 +199,23 @@
             "openWorldHint": False,
         },
     ),
+    (
+        "axguard_verify_fix",
+        (
+            "Re-analyze after a remediation and classify the prior finding as "
+            "RESOLVED, STILL_PRESENT, or REGRESSED using fingerprints — never "
+            "mark resolved solely because a file path changed. Call after the "
+            "agent applies a fix for a known finding. Read-only re-scan. "
+            "Requires approved=true. Does not modify source."
+        ),
+        {
+            "title": "Verify Fix",
+            "readOnlyHint": True,
+            "destructiveHint": False,
+            "idempotentHint": False,
+            "openWorldHint": False,
+        },
+    ),
     (
         "axguard_get_evidence",
         (

diff --git a/engines/mcp/tools/handlers.py b/engines/mcp/tools/handlers.py
@@ -275,6 +275,23 @@ def axguard_verify_finding(finding_id: str | None = None, approved: bool = False
     )
 
 
+def axguard_verify_fix(
+    finding_id: str | None = None,
+    fingerprint: str | None = None,
+    path: str | None = None,
+    approved: bool = False,
+) -> dict[str, Any]:
+    from engines.mcp.tools.verify_fix import run_verify_fix
+
+    return run_verify_fix(
+        finding_id=finding_id,
+        fingerprint=fingerprint,
+        path=path,
+        approved=approved,
+        session=_sess(),
+    )
+
+
 def _ensure_evidence(sess: McpSession) -> dict[str, Any]:
     if sess.last_evidence:
         return sess.last_evidence
@@ -650,6 +667,7 @@ def axguard_security_review_tool(
     "axguard_list_findings": as_tool(axguard_list_findings),
     "axguard_get_finding": as_tool(axguard_get_finding),
     "axguard_verify_finding": as_tool(axguard_verify_finding),
+    "axguard_verify_fix": as_tool(axguard_verify_fix),
     "axguard_get_evidence": as_tool(axguard_get_evidence),
     "axguard_get_evidence_chain": as_tool(axguard_get_evidence_chain),
     "axguard_get_counter_evidence": as_tool(axguard_get_counter_evidence),