agentsentinel-cli 0.6.1__tar.gz → 0.7.0__tar.gz

{agentsentinel_cli-0.6.1 → agentsentinel_cli-0.7.0}/DOCUMENTATION.md

@@ -20,6 +20,7 @@ No server required. No Docker. Works on any Python agent file or live HTTP endpo
   - [sentinel mcp scan](#sentinel-mcp-scan)
   - [sentinel probe](#sentinel-probe)
   - [sentinel ai-probe](#sentinel-ai-probe)
+- [Finding Suppression](#finding-suppression)
 - [Real-World Workflows](#real-world-workflows)
 - [CI/CD Integration](#cicd-integration)
 - [Reference](#reference)
@@ -119,6 +120,7 @@ TARGET can be a Python file, a directory, or a live HTTP endpoint URL.
 | `--model TEXT` | `claude-haiku-4-5-20251001` | Claude model for AI summary |
 | `--auth-header HEADER` | — | HTTP auth header for live endpoints, e.g. `Authorization: Bearer token` |
 | `--fail-on [CRITICAL\|HIGH\|MEDIUM\|LOW]` | — | Exit code 1 if findings reach this severity |
+| `--ignore-rule RULE_ID` | — | Suppress a finding by rule ID. Repeatable. Also reads `.sentinelignore` in the target directory |
 
 #### What it shows
 
@@ -155,6 +157,9 @@ sentinel inspect http://my-agent.internal/chat \
 # JSON output — pipe into jq, SIEM, dashboards
 sentinel inspect my_agent.py --format json | jq '.fingerprint'
 
+# Suppress a known-accepted finding while still gating on CRITICAL
+sentinel inspect my_agent.py --fail-on CRITICAL --ignore-rule DANGEROUS_GRANTS
+
 # CI gate — fail if any CRITICAL finding
 sentinel inspect my_agent.py --fail-on CRITICAL
 ```
@@ -220,6 +225,7 @@ TARGET defaults to `.` (current directory, scanned recursively).
 |------|---------|-------------|
 | `--format [text\|json]` | `text` | Output format |
 | `--fail-on [CRITICAL\|HIGH\|MEDIUM\|LOW]` | — | Exit code 1 if findings reach this severity |
+| `--ignore-rule RULE_ID` | — | Suppress a finding by rule ID. Repeatable. Also reads `.sentinelignore` in the target directory |
 | `--connect URL` | — | Pull live behavior data from a running AgentSentinel instance |
 | `--api-key TEXT` | `$AGENTSENTINEL_API_KEY` | API key for `--connect` |
 
@@ -268,6 +274,14 @@ sentinel scan my_agent.py --format json
 
 # Include live behavior data from a running AgentSentinel instance
 sentinel scan my_agent.py --connect http://localhost:9000 --api-key $AGENTSENTINEL_KEY
+
+# Suppress a noisy LOW finding and still gate on HIGH
+sentinel scan ./agents/ --fail-on HIGH --ignore-rule MISSING_RATE_LIMIT
+
+# Stack multiple suppressions
+sentinel scan ./agents/ --fail-on CRITICAL \
+  --ignore-rule MISSING_RATE_LIMIT \
+  --ignore-rule TOOL_SPRAWL
 ```
 
 #### Example output
@@ -342,6 +356,7 @@ sentinel secrets ~/.claude/projects/ --severity LOW
 | `--format [text\|json]` | `text` | Output format |
 | `--fail-on [CRITICAL\|HIGH\|MEDIUM\|LOW]` | — | Exit code 1 if findings reach this severity |
 | `--no-redact` | off | Show full matched values instead of masking them |
+| `--ignore-rule RULE_ID` | — | Suppress a finding by rule ID. Repeatable. Also reads `.sentinelignore` in the target directory |
 
 #### Choosing the right scope
 
@@ -597,8 +612,8 @@ Common false positives and how to handle them:
 | `SG_UEN` | 9-digit numbers that happen to end in a letter | UENs are common in business documents — confirm the surrounding context |
 
 If a finding is a confirmed false positive, it does not affect the finding count for `--fail-on`
-evaluation — you still need to address it or suppress it by restructuring the content.
-Suppression via ignore-lists is not yet implemented (planned for v0.6).
+evaluation — you still need to address it, suppress it with `--ignore-rule`, or restructure the
+content to remove the match. See [Finding Suppression](#finding-suppression).
 
 ---
 
@@ -692,6 +707,7 @@ sentinel mcp scan --stdio "CMD" [OPTIONS]
 | `--format [text\|json]` | `text` | Output format |
 | `--timeout SECONDS` | `10.0` | Connection timeout |
 | `--fail-on [CRITICAL\|HIGH\|MEDIUM\|LOW]` | — | Exit code 1 if findings reach this severity |
+| `--ignore-rule RULE_ID` | — | Suppress a finding by rule ID. Repeatable. Also reads `.sentinelignore` in the working directory |
 
 #### Transport support
 
@@ -740,6 +756,9 @@ sentinel mcp scan http://localhost:3000 --fail-on CRITICAL
 
 # Longer timeout for slow servers
 sentinel mcp scan http://remote-server.com/mcp --timeout 30
+
+# CI gate — suppress a finding accepted at the infrastructure layer
+sentinel mcp scan http://localhost:3000 --fail-on CRITICAL --ignore-rule NO_AUTH
 ```
 
 #### Example output
@@ -958,6 +977,87 @@ sentinel ai-probe http://my-agent.com/chat --fail-on CRITICAL
 
 ---
 
+## Finding Suppression
+
+Use `--ignore-rule` and `.sentinelignore` to suppress specific findings by rule ID. Suppressed findings are excluded from both output display and `--fail-on` evaluation — they never break a CI gate.
+
+Supported commands: `sentinel scan`, `sentinel mcp scan`, `sentinel supply-chain`, `sentinel secrets`, `sentinel inspect`.
+
+### --ignore-rule flag
+
+Suppress one or more rules for a single run. The flag is repeatable.
+
+```bash
+# Suppress a single rule
+sentinel scan ./agents/ --fail-on HIGH --ignore-rule MISSING_RATE_LIMIT
+
+# Stack multiple suppressions
+sentinel mcp scan http://localhost:3001 --fail-on CRITICAL \
+  --ignore-rule NO_AUTH \
+  --ignore-rule UNBOUNDED_INPUT
+
+# Suppress during secrets scan
+sentinel secrets . --fail-on HIGH --ignore-rule SG_UEN
+```
+
+### .sentinelignore file
+
+For persistent, project-level suppressions, create a `.sentinelignore` file and commit it to source control. sentinel walks up from the target directory to find it — same discovery pattern as `.gitignore`.
+
+```
+# .sentinelignore
+
+# Comments start with #. Blank lines are ignored.
+# Rule IDs are case-insensitive.
+
+MISSING_RATE_LIMIT          # rate limiting enforced at API gateway layer
+SC03_HIDDEN_NETWORK_FIELDS  # webhook field is for audit logging — verified safe
+NO_AUTH                     # MCP server is behind an authenticated reverse proxy
+```
+
+sentinel searches for `.sentinelignore` starting from the target path and walking up to the filesystem root. For URL targets (`sentinel mcp scan`, `sentinel supply-chain`), it searches from the current working directory.
+
+### Suppression notice
+
+When findings are suppressed, sentinel prints a dim notice at the end of text output:
+
+```
+  1 finding suppressed by .sentinelignore / --ignore-rule: MISSING_RATE_LIMIT
+```
+
+In JSON output, suppressed findings are absent from the `findings` array. The `--fail-on` threshold is evaluated only against the active (non-suppressed) findings.
+
+### What to suppress — and what not to
+
+Suppressions are appropriate for findings where the risk is genuinely accepted at another layer:
+
+| Scenario | Appropriate suppression |
+|----------|------------------------|
+| Rate limiting handled at API gateway | `MISSING_RATE_LIMIT` |
+| MCP server behind authenticated proxy | `NO_AUTH` |
+| Known webhook field verified safe | `SC03_HIDDEN_NETWORK_FIELDS` |
+| Agent description intentionally omitted | `UNDESCRIBED_WRITE_AGENT` |
+
+Do not suppress CRITICAL findings (`EXFILTRATION_PATH`, `CODE_EXECUTION_GRANT`, `HARDCODED_CREDENTIALS`, `SC01_DESCRIPTION_INJECTION`) without a very specific, documented reason. These represent confirmed active risk paths, not configuration preferences.
+
+### Incremental CI adoption
+
+The `.sentinelignore` + `--fail-on` combination is the recommended way to adopt CI gates incrementally:
+
+```bash
+# Week 1 — gate only on CRITICAL, suppress anything that isn't actually critical
+sentinel scan ./agents/ --fail-on CRITICAL
+
+# Week 2 — raise threshold to HIGH, suppress accepted HIGH findings
+echo "DANGEROUS_GRANTS" >> .sentinelignore
+sentinel scan ./agents/ --fail-on HIGH
+
+# Week 3 — full posture gate, suppressions document accepted risk
+sentinel scan ./agents/ --fail-on MEDIUM
+```
+
+---
+
 ## Real-World Workflows
 
 ### Workflow 1: Unknown agent found in production
@@ -1121,6 +1221,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+        # .sentinelignore in the repo root is picked up automatically
 
       - name: Install sentinel
         run: pip install "agentsentinel-cli[all]"
@@ -1146,6 +1247,13 @@ jobs:
         run: sentinel mcp scan http://localhost:3000 --fail-on CRITICAL
 ```
 
+Add a `.sentinelignore` at the repo root to suppress known-accepted findings without weakening the gate threshold:
+
+```
+# .sentinelignore — committed to source control
+MISSING_RATE_LIMIT    # rate limiting handled at infra layer
+```
+
 ### GitLab CI
 
 ```yaml

{agentsentinel_cli-0.6.1 → agentsentinel_cli-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentsentinel-cli
-Version: 0.6.1
+Version: 0.7.0
 Summary: Agentic security CLI — AI analyst with memory, supply chain audit, MCP audit, red-team probing, and agent discovery
 Project-URL: Homepage, https://github.com/jaydenaung/agentsentinel-cli
 Project-URL: Repository, https://github.com/jaydenaung/agentsentinel-cli
@@ -195,6 +195,7 @@ sentinel scan my_agent.py
 sentinel scan ./agents/
 sentinel scan my_agent.py --fail-on CRITICAL    # CI gate
 sentinel scan my_agent.py --format json
+sentinel scan ./agents/ --fail-on HIGH --ignore-rule MISSING_RATE_LIMIT  # suppress known-accepted finding
 ```
 
 **Rules:**
@@ -299,6 +300,35 @@ sentinel discover --format json
 
 ---
 
+## Finding suppression
+
+Use `--ignore-rule` to suppress specific findings by rule ID. Suppressed findings are excluded from `--fail-on` evaluation and output — they don't break CI gates.
+
+```bash
+# Suppress a single finding for one run
+sentinel scan ./agents/ --fail-on HIGH --ignore-rule MISSING_RATE_LIMIT
+
+# Stack multiple suppressions
+sentinel mcp scan http://localhost:3001 --fail-on CRITICAL \
+  --ignore-rule NO_AUTH \
+  --ignore-rule UNBOUNDED_INPUT
+```
+
+For project-level suppressions, create a **`.sentinelignore`** file in your project root. sentinel walks up from the target directory to find it — the same discovery pattern as `.gitignore`.
+
+```
+# .sentinelignore
+# Comments start with #
+
+MISSING_RATE_LIMIT          # rate limiting enforced at API gateway
+SC03_HIDDEN_NETWORK_FIELDS  # webhook field verified safe — used for audit logging
+NO_AUTH                     # server is behind an authenticated reverse proxy
+```
+
+Supported on: `sentinel scan`, `sentinel mcp scan`, `sentinel supply-chain`, `sentinel secrets`, `sentinel inspect`.
+
+---
+
 ## OWASP Top 10 for Agentic Applications 2026 coverage
 
 | OWASP Risk | ID | sentinel coverage |
@@ -345,6 +375,13 @@ jobs:
         run: sentinel mcp scan http://localhost:3001 --fail-on CRITICAL
 ```
 
+Use a `.sentinelignore` file at the repo root to suppress known-accepted findings without weakening the gate threshold:
+
+```
+# .sentinelignore — committed to source control
+MISSING_RATE_LIMIT    # rate limiting handled at infra layer
+```
+
 ---
 
 ## When to use analyst mode vs. static mode
@@ -352,6 +389,7 @@ jobs:
 | Situation | Use |
 |-----------|-----|
 | CI/CD gate on every PR | Static rules (`--fail-on CRITICAL`) |
+| Adopting CI gates incrementally | Static rules + `.sentinelignore` to suppress accepted risks |
 | Investigating a specific server or codebase | `sentinel agentic` |
 | First assessment of a new MCP server | `sentinel agentic` |
 | Scheduled nightly security check | `sentinel agentic` (memory tracks drift) |

{agentsentinel_cli-0.6.1 → agentsentinel_cli-0.7.0}/README.md

@@ -148,6 +148,7 @@ sentinel scan my_agent.py
 sentinel scan ./agents/
 sentinel scan my_agent.py --fail-on CRITICAL    # CI gate
 sentinel scan my_agent.py --format json
+sentinel scan ./agents/ --fail-on HIGH --ignore-rule MISSING_RATE_LIMIT  # suppress known-accepted finding
 ```
 
 **Rules:**
@@ -252,6 +253,35 @@ sentinel discover --format json
 
 ---
 
+## Finding suppression
+
+Use `--ignore-rule` to suppress specific findings by rule ID. Suppressed findings are excluded from `--fail-on` evaluation and output — they don't break CI gates.
+
+```bash
+# Suppress a single finding for one run
+sentinel scan ./agents/ --fail-on HIGH --ignore-rule MISSING_RATE_LIMIT
+
+# Stack multiple suppressions
+sentinel mcp scan http://localhost:3001 --fail-on CRITICAL \
+  --ignore-rule NO_AUTH \
+  --ignore-rule UNBOUNDED_INPUT
+```
+
+For project-level suppressions, create a **`.sentinelignore`** file in your project root. sentinel walks up from the target directory to find it — the same discovery pattern as `.gitignore`.
+
+```
+# .sentinelignore
+# Comments start with #
+
+MISSING_RATE_LIMIT          # rate limiting enforced at API gateway
+SC03_HIDDEN_NETWORK_FIELDS  # webhook field verified safe — used for audit logging
+NO_AUTH                     # server is behind an authenticated reverse proxy
+```
+
+Supported on: `sentinel scan`, `sentinel mcp scan`, `sentinel supply-chain`, `sentinel secrets`, `sentinel inspect`.
+
+---
+
 ## OWASP Top 10 for Agentic Applications 2026 coverage
 
 | OWASP Risk | ID | sentinel coverage |
@@ -298,6 +328,13 @@ jobs:
         run: sentinel mcp scan http://localhost:3001 --fail-on CRITICAL
 ```
 
+Use a `.sentinelignore` file at the repo root to suppress known-accepted findings without weakening the gate threshold:
+
+```
+# .sentinelignore — committed to source control
+MISSING_RATE_LIMIT    # rate limiting handled at infra layer
+```
+
 ---
 
 ## When to use analyst mode vs. static mode
@@ -305,6 +342,7 @@ jobs:
 | Situation | Use |
 |-----------|-----|
 | CI/CD gate on every PR | Static rules (`--fail-on CRITICAL`) |
+| Adopting CI gates incrementally | Static rules + `.sentinelignore` to suppress accepted risks |
 | Investigating a specific server or codebase | `sentinel agentic` |
 | First assessment of a new MCP server | `sentinel agentic` |
 | Scheduled nightly security check | `sentinel agentic` (memory tracks drift) |

agentsentinel_cli-0.7.0/agentsentinel_cli/a2a_report.py

@@ -0,0 +1,236 @@
+"""Rich terminal and JSON output for sentinel a2a — multi-agent trust analysis."""
+
+import json
+
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+from rich import box
+from rich.text import Text
+
+from agentsentinel_cli.a2a_scanner import A2AGraph, AgentNode, A2AEdge
+from agentsentinel_cli.a2a_rules import A2AFinding, a2a_posture_score
+
+console = Console()
+
+_SEVERITY_COLOR = {
+    "CRITICAL": "bold red",
+    "HIGH":     "bold orange1",
+    "MEDIUM":   "bold yellow",
+    "LOW":      "bold cyan",
+}
+_STATUS_COLOR = {
+    "TRUSTED":  "bold green",
+    "WATCH":    "bold yellow",
+    "ALERT":    "bold orange1",
+    "CRITICAL": "bold red",
+}
+_FRAMEWORK_COLOR = {
+    "autogen":   "cyan",
+    "langchain": "green",
+    "langgraph": "bright_green",
+    "crewai":    "magenta",
+    "generic":   "dim",
+}
+_ROLE_TAG = {
+    "orchestrator": "[bold white]orchestrator[/bold white]",
+    "worker":       "[dim]worker[/dim]",
+    "peer":         "[dim]peer[/dim]",
+    "unknown":      "[dim]unknown[/dim]",
+}
+
+
+def _status_label(score: int) -> str:
+    if score >= 80:
+        return "TRUSTED"
+    if score >= 60:
+        return "WATCH"
+    if score >= 40:
+        return "ALERT"
+    return "CRITICAL"
+
+
+def print_a2a_result(
+    graph: A2AGraph,
+    findings: list[A2AFinding],
+    score: int,
+    target: str,
+) -> None:
+    status       = _status_label(score)
+    status_color = _STATUS_COLOR[status]
+
+    console.print()
+    console.print(Panel.fit(
+        f"[bold white]AgentSentinel A2A Trust Analysis[/bold white]\n"
+        f"[dim]Target: {target}[/dim]",
+        border_style="bright_blue",
+        padding=(0, 2),
+    ))
+
+    if not graph.nodes:
+        console.print(
+            "\n  [yellow]No multi-agent patterns detected.[/yellow]\n"
+            "  [dim]sentinel a2a recognises LangChain/LangGraph, AutoGen, and CrewAI patterns.[/dim]\n"
+        )
+        return
+
+    # ── Call graph summary ────────────────────────────────────────────────────
+    has_cycles  = graph.has_cycles
+    max_depth   = graph.max_depth
+    cycle_tag   = "[bold red]⚠ cycle[/bold red]" if has_cycles else "[dim green]acyclic[/dim green]"
+
+    console.print(
+        f"\n  [bold white]{len(graph.nodes)}[/bold white] agents  "
+        f"[bold white]{len(graph.edges)}[/bold white] edges  "
+        f"[bold white]{max_depth}[/bold white] max depth  "
+        f"{cycle_tag}"
+    )
+
+    # ── Agent nodes table ─────────────────────────────────────────────────────
+    console.print()
+    node_table = Table(box=box.SIMPLE, show_header=True, header_style="dim", padding=(0, 1))
+    node_table.add_column("Agent",      style="bold white", min_width=20)
+    node_table.add_column("Framework",  width=12)
+    node_table.add_column("Role",       width=14)
+    node_table.add_column("Tools",      style="dim", max_width=30)
+    node_table.add_column("",           width=16)
+
+    for node in graph.nodes:
+        fw_color  = _FRAMEWORK_COLOR.get(node.framework, "white")
+        role_text = _ROLE_TAG.get(node.role, node.role)
+        tools_str = ", ".join(node.tools[:3]) + ("…" if len(node.tools) > 3 else "")
+
+        flags = Text()
+        if node.has_code_execution:
+            flags.append("⚠ code exec", style="bold red")
+        if node.spawned_in_loop:
+            if flags.plain:
+                flags.append("  ")
+            flags.append("⟲ in loop", style="bold orange1")
+
+        node_table.add_row(
+            node.name,
+            Text(node.framework, style=fw_color),
+            Text.from_markup(role_text),
+            tools_str or "—",
+            flags,
+        )
+    console.print(node_table)
+
+    # ── Call graph edges ──────────────────────────────────────────────────────
+    if graph.edges:
+        console.print("  [dim]Call graph:[/dim]")
+        shown: set[tuple[str, str]] = set()
+        for edge in graph.edges:
+            key = (edge.caller, edge.callee)
+            if key in shown:
+                continue
+            shown.add(key)
+            tags = []
+            if edge.passes_user_input:
+                tags.append("[bold orange1]passes input[/bold orange1]")
+            if not edge.callee_tools_scoped:
+                tags.append("[yellow]unscoped tools[/yellow]")
+            tag_str = "  " + "  ".join(tags) if tags else ""
+            arrow = "──►" if edge.call_type != "group_member" else "◄──►"
+            console.print(
+                f"    [dim white]{edge.caller}[/dim white] "
+                f"[dim]{arrow}[/dim] "
+                f"[bold white]{edge.callee}[/bold white]"
+                f"  [dim]{edge.call_type}[/dim]{tag_str}"
+            )
+        console.print()
+
+    # ── Findings ──────────────────────────────────────────────────────────────
+    if findings:
+        for f in findings:
+            color = _SEVERITY_COLOR.get(f.severity, "white")
+            console.print(
+                f"  [{color}]● {f.severity:<8}[/{color}]  "
+                f"[bold white]{f.rule_id}[/bold white]"
+                f"  [dim]{f.owasp}[/dim]"
+            )
+            console.print(f"  [dim]           {f.message}[/dim]")
+            if f.detail:
+                console.print(f"  [dim]           {f.detail}[/dim]")
+            console.print()
+    else:
+        console.print("  [green]✓ No trust findings[/green]\n")
+
+    # ── Score footer ──────────────────────────────────────────────────────────
+    bar_filled = int(score / 5)
+    bar = "█" * bar_filled + "░" * (20 - bar_filled)
+    console.print(
+        f"  Trust Score  [{status_color}]{score:>3}/100[/{status_color}]  "
+        f"[dim]{bar}[/dim]  [{status_color}]{status}[/{status_color}]"
+    )
+
+    n_critical = sum(1 for f in findings if f.severity == "CRITICAL")
+    n_high     = sum(1 for f in findings if f.severity == "HIGH")
+
+    console.print()
+    console.rule(style="bright_blue")
+    parts = [
+        f"[bold white]{len(graph.nodes)}[/bold white] agent{'s' if len(graph.nodes) != 1 else ''}",
+        f"[bold white]{len(graph.edges)}[/bold white] edge{'s' if len(graph.edges) != 1 else ''}",
+        f"[bold white]{len(findings)}[/bold white] finding{'s' if len(findings) != 1 else ''}",
+    ]
+    if n_critical:
+        parts.append(f"[bold red]{n_critical} CRITICAL[/bold red]")
+    if n_high:
+        parts.append(f"[bold orange1]{n_high} HIGH[/bold orange1]")
+    console.print("  " + " · ".join(parts))
+    console.print()
+
+
+def as_a2a_json(
+    graph: A2AGraph,
+    findings: list[A2AFinding],
+    score: int,
+    target: str,
+) -> str:
+    return json.dumps({
+        "target": target,
+        "agent_count": len(graph.nodes),
+        "edge_count": len(graph.edges),
+        "has_cycles": graph.has_cycles,
+        "max_depth": graph.max_depth,
+        "agents": [
+            {
+                "name": n.name,
+                "framework": n.framework,
+                "role": n.role,
+                "tools": n.tools,
+                "has_code_execution": n.has_code_execution,
+                "spawned_in_loop": n.spawned_in_loop,
+                "file": str(n.file),
+                "line": n.line,
+            }
+            for n in graph.nodes
+        ],
+        "edges": [
+            {
+                "caller": e.caller,
+                "callee": e.callee,
+                "call_type": e.call_type,
+                "passes_user_input": e.passes_user_input,
+                "callee_tools_scoped": e.callee_tools_scoped,
+                "file": str(e.file),
+                "line": e.line,
+            }
+            for e in graph.edges
+        ],
+        "findings": [
+            {
+                "severity": f.severity,
+                "rule_id": f.rule_id,
+                "message": f.message,
+                "detail": f.detail,
+                "node_name": f.node_name,
+                "owasp": f.owasp,
+            }
+            for f in findings
+        ],
+        "trust_score": score,
+        "status": _status_label(score),
+    }, indent=2)