agentsec-cli 0.1.0__py3-none-any.whl

agentsec/__init__.py

@@ -0,0 +1,3 @@
+"""AgentSec: Static security scanner for AI coding agents and MCP configs."""
+
+__version__ = "0.1.0"

agentsec/baseline.py

@@ -0,0 +1,60 @@
+"""Baseline (lockfile) management for AgentSec."""
+
+import json
+import hashlib
+from pathlib import Path
+from typing import Dict, List, Tuple
+
+
+def compute_finding_id(finding: dict) -> str:
+    """Compute a stable unique ID for a finding based on rule, file, and server."""
+    key = f"{finding['rule']}|{finding['file']}|{finding.get('server', '')}"
+    return hashlib.md5(key.encode()).hexdigest()
+
+
+def load_baseline(path: str) -> Dict[str, str]:
+    """Load baseline from JSON file. Returns dict of id -> severity."""
+    p = Path(path)
+    if not p.exists():
+        return {}
+    with open(p, 'r') as f:
+        data = json.load(f)
+    return data.get('findings', {})
+
+
+def save_baseline(path: str, findings: List[dict]) -> None:
+    """Save current findings as baseline."""
+    baseline = {}
+    for f in findings:
+        fid = compute_finding_id(f)
+        baseline[fid] = f['severity']
+    with open(path, 'w') as f:
+        json.dump({"findings": baseline}, f, indent=2)
+
+
+def compare_findings(findings: List[dict], baseline: Dict[str, str]) -> Tuple[List[dict], List[dict], List[dict]]:
+    """
+    Compare current findings against baseline.
+    Returns: (new, changed, removed)
+      - new: findings not in baseline
+      - changed: findings whose severity changed
+      - removed: baseline entries not in current findings (as list of dict with 'id' and 'severity')
+    """
+    current_ids = set()
+    new = []
+    changed = []
+
+    for f in findings:
+        fid = compute_finding_id(f)
+        current_ids.add(fid)
+        if fid not in baseline:
+            new.append(f)
+        elif baseline[fid] != f['severity']:
+            changed.append(f)
+
+    removed = []
+    for fid, sev in baseline.items():
+        if fid not in current_ids:
+            removed.append({'id': fid, 'severity': sev})
+
+    return new, changed, removed

agentsec/cli.py

@@ -0,0 +1,84 @@
+"""CLI entry point for AgentSec."""
+
+import sys
+import click
+from pathlib import Path
+from .scanner import Scanner
+from .report import print_summary
+from .baseline import load_baseline, save_baseline, compare_findings, compute_finding_id
+from .owasp import format_owasp
+
+
+@click.group()
+def cli():
+    """AgentSec — security scanner for AI agent configs."""
+    pass
+
+
+@cli.command()
+@click.argument("path", default=".", type=click.Path(exists=True, file_okay=False, dir_okay=True, resolve_path=True))
+@click.option("--format", "-f", default="terminal", help="Output format: terminal, json, markdown, sarif")
+@click.option("--severity", default="all", help="Minimum severity: critical, high, medium, low, all")
+@click.option("--fail-on", type=click.Choice(["critical", "high", "medium", "low"], case_sensitive=False), help="Exit with code 1 if any finding is at least this severity")
+@click.option("--include-hidden", is_flag=True, help="Include hidden files and directories")
+@click.option("--baseline", type=click.Path(exists=True, dir_okay=False, resolve_path=True), help="Path to baseline JSON file (lockfile). Compare findings against it.")
+@click.option("--update-baseline", type=click.Path(dir_okay=False, resolve_path=True), help="Save current findings as baseline JSON file and exit.")
+@click.option("--show-owasp", is_flag=True, default=False, help="Show OWASP Top 10 for LLM mapping IDs for each finding")
+def scan(path, format, severity, include_hidden, fail_on=None, baseline=None, update_baseline=None, show_owasp=False):
+    """Scan a directory for security risks in AI agent configurations."""
+    if format == "terminal":
+        click.echo(f" Scanning {path}...")
+    scanner = Scanner(Path(path), include_hidden=include_hidden, min_severity=severity)
+    findings = scanner.scan()
+
+    # If update-baseline is provided, save baseline and exit
+    if update_baseline:
+        save_baseline(update_baseline, findings)
+        if format == "terminal":
+            click.echo(f" Baseline saved to {update_baseline}")
+        return
+
+    # Load baseline if provided
+    if baseline:
+        baseline_findings = load_baseline(baseline)
+        new, changed, removed = compare_findings(findings, baseline_findings)
+        if format == "terminal":
+            click.echo(f"\n Baseline comparison against {baseline}:")
+            click.echo(f"  New findings: {len(new)}")
+            click.echo(f"  Changed severity: {len(changed)}")
+            click.echo(f"  Removed findings: {len(removed)}")
+            if new:
+                click.echo("\n New findings:")
+                for f in new:
+                    click.echo(f"  [{f['severity']}] {f['rule']} ({f['file']})")
+            if changed:
+                click.echo("\n Changed findings:")
+                for f in changed:
+                    old_sev = baseline_findings.get(compute_finding_id(f), 'unknown')
+                    click.echo(f"  [{old_sev} -> {f['severity']}] {f['rule']} ({f['file']})")
+            if removed:
+                click.echo("\n Removed findings (baseline only):")
+                for r in removed:
+                    click.echo(f"  [{r['severity']}] id: {r['id']}")
+        print_summary(findings, format, show_owasp=show_owasp)
+        if new or changed:
+            sys.exit(1)
+    else:
+        # Add OWASP tags to terminal output header if show_owasp
+        if format == "terminal" and show_owasp:
+            click.echo(" OWASP mapping enabled (LLM = OWASP Top 10 for LLM, AG = OWASP Agentic Security)\n")
+        print_summary(findings, format, show_owasp=show_owasp)
+
+    # Existing fail-on logic
+    if fail_on:
+        severity_levels = {"low": 0, "medium": 1, "high": 2, "critical": 3}
+        min_fail = severity_levels.get(fail_on.lower(), -1)
+        if min_fail >= 0:
+            for f in findings:
+                if severity_levels.get(f["severity"].lower(), -1) >= min_fail:
+                    click.echo(f"Failing due to {f['severity']} finding: {f['rule']}")
+                    sys.exit(1)
+
+
+if __name__ == "__main__":
+    cli()

agentsec/owasp.py

@@ -0,0 +1,212 @@
+"""OWASP Top 10 for LLM Applications — rule mapping for AgentSec.
+
+Maps each AgentSec rule to the relevant OWASP categories.
+
+OWASP Top 10 for LLM Applications (2025):
+https://genai.owasp.org/
+
+LLM01 — Prompt Injection
+LLM02 — Sensitive Information Disclosure
+LLM03 — Supply Chain Vulnerabilities
+LLM04 — Data Leakage via External Services
+LLM05 — Insecure Output Handling
+LLM06 — Excessive Agency / Unrestricted Autonomy
+LLM07 — Insecure Plugin / Extension Design
+LLM08 — Excessive Permissions / Overprivileged Access
+LLM09 — Over-reliance / Insufficient Oversight
+LLM10 — Model Theft / Intellectual Property Loss
+
+OWASP Agentic Security Top 10 (2025):
+AG01 — Insecure Agent-to-Agent Communication
+AG02 — Unauthorized Tool Access
+AG03 — Agent Impersonation
+AG04 — Task Delegation Abuse
+AG05 — Memory / Prompt Leakage
+AG06 — Inconsistent Authorization
+AG07 — Output Validation Failure
+AG08 — Agent Workflow Manipulation
+AG09 — Inadequate Audit Trail
+AG10 — Privilege Escalation
+"""
+
+# Mapping: OWASP ID -> (short name, description)
+OWASP_CATEGORIES = {
+    "LLM01": ("Prompt Injection", "Attacker injects malicious instructions via user prompts or indirect inputs"),
+    "LLM02": ("Sensitive Information Disclosure", "LLM or agent exposes sensitive data (secrets, PII, internal info)"),
+    "LLM03": ("Supply Chain Vulnerabilities", "Compromised dependencies, packages, or third-party components"),
+    "LLM04": ("Data Leakage via External Services", "Sensitive data exfiltrated through network calls, APIs, or integrations"),
+    "LLM05": ("Insecure Output Handling", "Agent output is not validated before being used in downstream operations"),
+    "LLM06": ("Excessive Agency", "Agent has more autonomy than necessary — can perform actions without oversight"),
+    "LLM07": ("Insecure Plugin/Extension Design", "Plugins or extensions have weak security boundaries"),
+    "LLM08": ("Excessive Permissions", "Agent or tool has overly broad filesystem/network/OS permissions"),
+    "LLM09": ("Over-reliance / Insufficient Oversight", "No guardrails, audit, or policy enforcement for agent actions"),
+    "LLM10": ("Model Theft / IP Loss", "Risk of proprietary model weights or IP extraction"),
+    # Agentic Security
+    "AG01": ("Insecure Agent-to-Agent Communication", "Agents communicate without proper authentication or encryption"),
+    "AG02": ("Unauthorized Tool Access", "Agent can invoke tools or capabilities without proper authorization gates"),
+    "AG03": ("Agent Impersonation", "Attacker impersonates a legitimate agent to gain access"),
+    "AG04": ("Task Delegation Abuse", "Malicious tasks can be delegated to sub-agents without validation"),
+    "AG05": ("Memory/Prompt Leakage", "Agent memory or prompt context can leak across sessions or users"),
+    "AG06": ("Inconsistent Authorization", "Authorization policies are missing, incomplete, or not enforced"),
+    "AG07": ("Output Validation Failure", "Agent output is not validated for safety or correctness"),
+    "AG08": ("Agent Workflow Manipulation", "Attacker manipulates the agent's workflow or decision chain"),
+    "AG09": ("Inadequate Audit Trail", "Agent actions are not logged or traceable"),
+    "AG10": ("Privilege Escalation", "Agent can escalate its own privileges beyond intended scope"),
+}
+
+# Rule-to-OWASP mapping: rule_name -> list of (owasp_id, category_name)
+# Covers all 41 rules from base.py + additional.py (deduplicated)
+RULE_OWASP_MAP = {
+    # === Base rules ===
+    "MCP shell execution": [
+        ("LLM06", "Excessive Agency"),
+        ("AG02", "Unauthorized Tool Access"),
+    ],
+    "MCP filesystem write access": [
+        ("LLM08", "Excessive Permissions"),
+    ],
+    "Secret exposure": [
+        ("LLM02", "Sensitive Information Disclosure"),
+    ],
+    "Broad path access": [
+        ("LLM08", "Excessive Permissions"),
+    ],
+    "Prompt injection risk": [
+        ("LLM01", "Prompt Injection"),
+    ],
+    "Sensitive file reference": [
+        ("LLM02", "Sensitive Information Disclosure"),
+    ],
+    "Excessive autonomy": [
+        ("LLM06", "Excessive Agency"),
+    ],
+    "Unpinned dependency": [
+        ("LLM03", "Supply Chain Vulnerabilities"),
+    ],
+    "Remote script install": [
+        ("LLM03", "Supply Chain Vulnerabilities"),
+    ],
+    "Docker socket access": [
+        ("LLM08", "Excessive Permissions"),
+        ("AG02", "Unauthorized Tool Access"),
+    ],
+    # === Additional rules ===
+    "Network + filesystem access": [
+        ("LLM04", "Data Leakage via External Services"),
+        ("AG05", "Memory/Prompt Leakage"),
+    ],
+    "Suspicious tool description": [
+        ("LLM01", "Prompt Injection"),
+        ("AG10", "Privilege Escalation"),
+    ],
+    "GitHub token exposure": [
+        ("LLM02", "Sensitive Information Disclosure"),
+        ("AG02", "Unauthorized Tool Access"),
+    ],
+    "Communication tool write permission": [
+        ("LLM04", "Data Leakage via External Services"),
+    ],
+    "Database write/delete permission": [
+        ("LLM08", "Excessive Permissions"),
+    ],
+    "Excessive autonomy instruction": [
+        ("LLM06", "Excessive Agency"),
+    ],
+    "Prompt injection in markdown": [
+        ("LLM01", "Prompt Injection"),
+    ],
+    "MCP OAuth broad scopes": [
+        ("LLM07", "Insecure Plugin/Extension Design"),
+        ("AG06", "Inconsistent Authorization"),
+    ],
+    "Web + filesystem access": [
+        ("LLM04", "Data Leakage via External Services"),
+        ("LLM08", "Excessive Permissions"),
+    ],
+    "Read repo + network": [
+        ("LLM04", "Data Leakage via External Services"),
+        ("AG05", "Memory/Prompt Leakage"),
+    ],
+    "Unknown/untrusted source": [
+        ("LLM03", "Supply Chain Vulnerabilities"),
+    ],
+    "No policy file": [
+        ("LLM09", "Over-reliance / Insufficient Oversight"),
+        ("AG06", "Inconsistent Authorization"),
+    ],
+    "Cursor agent config with dangerous permissions": [
+        ("LLM08", "Excessive Permissions"),
+        ("AG02", "Unauthorized Tool Access"),
+    ],
+    "Claude Desktop config with MCP server risks": [
+        ("LLM07", "Insecure Plugin/Extension Design"),
+    ],
+    "Codex/Cline agent with unrestricted tools": [
+        ("LLM08", "Excessive Permissions"),
+        ("AG02", "Unauthorized Tool Access"),
+    ],
+    "Environment variable exposure": [
+        ("LLM02", "Sensitive Information Disclosure"),
+    ],
+    "Vulnerable dependency pattern": [
+        ("LLM03", "Supply Chain Vulnerabilities"),
+    ],
+    "Insecure default command": [
+        ("LLM07", "Insecure Plugin/Extension Design"),
+    ],
+    "Read-only file system in MCP server": [
+        ("LLM08", "Excessive Permissions"),
+    ],
+    "Missing input validation": [
+        ("LLM05", "Insecure Output Handling"),
+        ("AG07", "Output Validation Failure"),
+    ],
+    "Package manager execution": [
+        ("LLM03", "Supply Chain Vulnerabilities"),
+    ],
+    "Container privileged mode": [
+        ("LLM08", "Excessive Permissions"),
+        ("AG02", "Unauthorized Tool Access"),
+    ],
+    "Host mount exposure": [
+        ("LLM08", "Excessive Permissions"),
+    ],
+    "Browser automation with local file access": [
+        ("LLM04", "Data Leakage via External Services"),
+        ("AG05", "Memory/Prompt Leakage"),
+    ],
+    "Dynamic code execution": [
+        ("LLM06", "Excessive Agency"),
+        ("AG10", "Privilege Escalation"),
+    ],
+    "Wildcard tool allowlist": [
+        ("LLM08", "Excessive Permissions"),
+    ],
+    "Telemetry or analytics endpoint": [
+        ("LLM04", "Data Leakage via External Services"),
+    ],
+    "Credential helper access": [
+        ("LLM02", "Sensitive Information Disclosure"),
+        ("AG02", "Unauthorized Tool Access"),
+    ],
+}
+
+
+def get_owasp(rule_name: str) -> list:
+    """Return OWASP mappings for a rule name. Returns [(owasp_id, category_name), ...] or empty list."""
+    return RULE_OWASP_MAP.get(rule_name, [])
+
+
+def get_owasp_ids(rule_name: str) -> str:
+    """Return OWASP IDs as a comma-separated string (e.g. 'LLM06, AG02')."""
+    mappings = get_owasp(rule_name)
+    return ", ".join(owasp_id for owasp_id, _ in mappings)
+
+
+def format_owasp(rule_name: str) -> str:
+    """Format OWASP info for terminal output: '[LLM06, AG02]' or empty string."""
+    mappings = get_owasp(rule_name)
+    if not mappings:
+        return ""
+    ids = ", ".join(f"{owasp_id}" for owasp_id, _ in mappings)
+    return f"[{ids}]"

agentsec/parsers/__init__.py

@@ -0,0 +1,5 @@
+"""File parsers for AgentSec."""
+
+from .core import parse_file
+
+__all__ = ["parse_file"]

agentsec/parsers/core.py

@@ -0,0 +1,8 @@
+from pathlib import Path
+
+def parse_file(file_path: Path) -> str | None:
+    try:
+        with open(file_path, 'r', encoding='utf-8') as f:
+            return f.read()
+    except Exception:
+        return None

agentsec/parsers/json_parser.py

@@ -0,0 +1,69 @@
+import json
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+def parse_mcp_config(content: str, file_path: Path) -> Optional[List[Dict[str, Any]]]:
+    """Parse MCP config from JSON content.
+    
+    Expects a JSON object with an 'mcpServers' key or a direct list of servers.
+    Returns a list of server dicts with keys: name, command, args, env, capabilities.
+    """
+    try:
+        data = json.loads(content)
+    except json.JSONDecodeError:
+        return None
+    
+    servers = []
+    
+    # Check for mcpServers object
+    if isinstance(data, dict) and "mcpServers" in data:
+        mcp_servers = data["mcpServers"]
+        if isinstance(mcp_servers, dict):
+            for name, config in mcp_servers.items():
+                if isinstance(config, dict):
+                    server = {
+                        "name": name,
+                        "command": config.get("command", ""),
+                        "args": config.get("args", []),
+                        "env": config.get("env", {}),
+                        "capabilities": _infer_capabilities(config)
+                    }
+                    servers.append(server)
+    elif isinstance(data, list):
+        # Maybe a list of servers
+        for item in data:
+            if isinstance(item, dict) and "command" in item:
+                server = {
+                    "name": item.get("name", ""),
+                    "command": item.get("command", ""),
+                    "args": item.get("args", []),
+                    "env": item.get("env", {}),
+                    "capabilities": _infer_capabilities(item)
+                }
+                servers.append(server)
+    return servers if servers else None
+
+def _infer_capabilities(config: Dict[str, Any]) -> List[str]:
+    """Infer capabilities from command, args, and env."""
+    caps = []
+    text = str(config).lower()
+    
+    # Filesystem
+    if "filesystem" in text or "write" in text or "edit" in text or "delete" in text or "rm" in text or "mv" in text:
+        caps.append("filesystem")
+    # Shell
+    if "bash" in text or "sh" in text or "powershell" in text or "cmd" in text or "exec" in text or "subprocess" in text or "terminal" in text or "run_command" in text:
+        caps.append("shell")
+    # Network
+    if "http" in text or "https" in text or "curl" in text or "wget" in text or "fetch" in text:
+        caps.append("network")
+    # Secrets
+    if "env" in text or ".env" in text or "secret" in text or "token" in text or "key" in text:
+        caps.append("secrets")
+    # Slack/email/github
+    if "slack" in text or "gmail" in text or "email" in text or "send_message" in text or "post_message" in text or "create_issue" in text or "comment" in text or "reply" in text:
+        caps.append("communication")
+    # Database
+    if "postgres" in text or "mysql" in text or "mongodb" in text or "redis" in text or "delete" in text or "drop" in text or "update" in text or "insert" in text:
+        caps.append("database")
+    return caps

agentsec/parsers/toml_parser.py

@@ -0,0 +1,28 @@
+import tomllib
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+from .json_parser import _infer_capabilities
+
+def parse_mcp_config(content: str, file_path: Path) -> Optional[List[Dict[str, Any]]]:
+    """Parse MCP config from TOML content."""
+    try:
+        data = tomllib.loads(content)
+    except (tomllib.TOMLDecodeError, TypeError):
+        return None
+    
+    if not isinstance(data, dict):
+        return None
+    
+    servers = []
+    if "mcpServers" in data and isinstance(data["mcpServers"], dict):
+        for name, config in data["mcpServers"].items():
+            if isinstance(config, dict):
+                server = {
+                    "name": name,
+                    "command": config.get("command", ""),
+                    "args": config.get("args", []),
+                    "env": config.get("env", {}),
+                    "capabilities": _infer_capabilities(config)
+                }
+                servers.append(server)
+    return servers if servers else None

agentsec/parsers/yaml_parser.py

@@ -0,0 +1,28 @@
+import yaml
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+from .json_parser import _infer_capabilities
+
+def parse_mcp_config(content: str, file_path: Path) -> Optional[List[Dict[str, Any]]]:
+    """Parse MCP config from YAML content."""
+    try:
+        data = yaml.safe_load(content)
+    except yaml.YAMLError:
+        return None
+    
+    if not isinstance(data, dict):
+        return None
+    
+    servers = []
+    if "mcpServers" in data and isinstance(data["mcpServers"], dict):
+        for name, config in data["mcpServers"].items():
+            if isinstance(config, dict):
+                server = {
+                    "name": name,
+                    "command": config.get("command", ""),
+                    "args": config.get("args", []),
+                    "env": config.get("env", {}),
+                    "capabilities": _infer_capabilities(config)
+                }
+                servers.append(server)
+    return servers if servers else None

agentsec/report.py

@@ -0,0 +1,36 @@
+"""Output formatters for AgentSec findings."""
+
+def print_summary(findings: list, format: str, show_owasp: bool = False) -> None:
+    """Print findings in the requested format."""
+    if format == "terminal":
+        for f in findings:
+            owasp_tag = f" {f.get('owasp', '')}" if show_owasp and f.get('owasp') else ""
+            print(f"[{f['severity'].upper()}]{owasp_tag} {f['rule']}")
+            print(f"  File: {f['file']}")
+            if f.get('server'):
+                print(f"  Server: {f['server']}")
+            print(f"  Description: {f['description']}")
+            print(f"  Recommendation: {f['recommendation']}")
+            if show_owasp and f.get('owasp'):
+                print(f"  OWASP: {f['owasp']}")
+            print()
+        print(f"Total findings: {len(findings)}")
+    elif format == "json":
+        import json
+        print(json.dumps(findings, indent=2))
+    elif format == "markdown":
+        print("# AgentSec Report\n")
+        for f in findings:
+            owasp_tag = f" ({f.get('owasp')})" if show_owasp and f.get('owasp') else ""
+            print(f"## {f['severity'].upper()}: {f['rule']}{owasp_tag}")
+            print(f"**File:** {f['file']}")
+            if f.get('server'):
+                print(f"**Server:** {f['server']}")
+            print(f"**Description:** {f['description']}")
+            print(f"**Recommendation:** {f['recommendation']}")
+            if show_owasp and f.get('owasp'):
+                print(f"**OWASP:** {f['owasp']}")
+            print()
+    elif format == "sarif":
+        from .sarif import print_sarif
+        print_sarif(findings)

agentsec/rules/__init__.py

@@ -0,0 +1,5 @@
+"""Security rules for AgentSec."""
+
+from .base import Rule, load_rules
+
+__all__ = ["Rule", "load_rules"]