ci-agent-audit 0.1.0__py3-none-any.whl

ci_agent_audit/__init__.py

@@ -0,0 +1,3 @@
+"""ci-agent-audit: Static security auditor for AI-powered CI/CD workflows."""
+
+__version__ = "0.1.0"

ci_agent_audit/cli.py

@@ -0,0 +1,251 @@
+"""Command-line interface for ci-agent-audit."""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+import sys
+from typing import Sequence
+
+import yaml
+
+from ci_agent_audit import __version__
+from ci_agent_audit.fixer import apply_fixes_to_file
+from ci_agent_audit.formatters import (
+    format_github_annotations,
+    format_json,
+    format_sarif,
+    format_text,
+)
+from ci_agent_audit.models import Finding, Severity
+from ci_agent_audit.rules import RULES_CATALOG, scan_workflow_file
+from ci_agent_audit.signatures_loader import SignatureValidationError, load_signatures
+
+
+def _discover_workflow_files(paths: Sequence[str]) -> list[Path]:
+    discovered: list[Path] = []
+    for raw in paths:
+        p = Path(raw)
+        if p.is_file():
+            discovered.append(p)
+        elif p.is_dir():
+            for ext in ("*.yml", "*.yaml"):
+                discovered.extend(sorted(p.rglob(ext)))
+    # Deduplicate while preserving order
+    seen: set[Path] = set()
+    unique: list[Path] = []
+    for item in discovered:
+        resolved = item.resolve()
+        if resolved not in seen:
+            seen.add(resolved)
+            unique.append(item)
+    return unique
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="ci-agent-audit",
+        description=(
+            "Static security auditor for AI-powered CI/CD workflows (GitHub Actions & GitLab CI). "
+            "Detects PromptPwnd indirect prompt injections, [bot] bypasses, dangerous agent flags, "
+            "and unpinned MCP servers."
+        ),
+    )
+    parser.add_argument("--version", action="version", version=f"ci-agent-audit {__version__}")
+
+    subparsers = parser.add_subparsers(dest="command")
+
+    # `scan` command
+    scan_p = subparsers.add_parser("scan", help="Scan workflow files or directories for AI CI security risks")
+    scan_p.add_argument(
+        "paths",
+        nargs="*",
+        default=[".github/workflows"],
+        help="Workflow files or directories to scan (default: .github/workflows)",
+    )
+    scan_p.add_argument(
+        "--format",
+        choices=["text", "json", "sarif", "github"],
+        default="text",
+        help="Output format (default: text)",
+    )
+    scan_p.add_argument(
+        "--severity",
+        choices=["low", "medium", "high", "critical"],
+        default="low",
+        help="Minimum severity level to report (default: low)",
+    )
+    scan_p.add_argument(
+        "--fail-on",
+        choices=["low", "medium", "high", "critical", "none"],
+        default="high",
+        help="Minimum severity level that causes a non-zero exit code (default: high)",
+    )
+    scan_p.add_argument(
+        "--ignore-rule",
+        action="append",
+        default=[],
+        help="Rule ID to ignore (can be specified multiple times, e.g. --ignore-rule AIA006)",
+    )
+    scan_p.add_argument(
+        "--signatures-dir",
+        action="append",
+        default=[],
+        help="Additional directory of custom YAML tool signatures",
+    )
+    scan_p.add_argument(
+        "--output",
+        "-o",
+        help="Write formatted report to a file instead of stdout",
+    )
+    scan_p.add_argument(
+        "--fix",
+        action="store_true",
+        help="Apply safe, deterministic fixes in-place before scanning",
+    )
+
+    # `rules` command
+    subparsers.add_parser("rules", help="List all built-in security audit rules (AIA001 - AIA011)")
+
+    # `explain` command
+    explain_p = subparsers.add_parser("explain", help="Show detailed documentation and remediation for a rule")
+    explain_p.add_argument("rule_id", help="Rule ID (e.g. AIA001)")
+
+    # `signatures` command
+    subparsers.add_parser("signatures", help="List all loaded AI Action & CLI tool signatures")
+
+    # `validate-signatures` command (for contributors adding new 1-file signatures)
+    val_p = subparsers.add_parser(
+        "validate-signatures",
+        help="Validate all built-in and custom YAML signature files against the schema",
+    )
+    val_p.add_argument(
+        "dirs",
+        nargs="*",
+        default=[],
+        help="Optional extra signature directories to validate",
+    )
+
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    if hasattr(sys.stdout, "reconfigure"):
+        try:
+            sys.stdout.reconfigure(encoding="utf-8")
+        except Exception:
+            pass
+
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    if not args.command:
+        parser.print_help()
+        return 0
+
+    if args.command == "rules":
+        for rule_id, meta in sorted(RULES_CATALOG.items()):
+            print(f"{rule_id} [{meta.severity.value.upper()}] {meta.name}")
+            print(f"  {meta.short_description}")
+        return 0
+
+    if args.command == "explain":
+        rid = args.rule_id.upper()
+        if rid not in RULES_CATALOG:
+            print(f"Error: Unknown rule ID '{args.rule_id}'. Run `ci-agent-audit rules` to list rules.", file=sys.stderr)
+            return 2
+        meta = RULES_CATALOG[rid]
+        print(f"Rule:        {meta.rule_id} ({meta.name})")
+        print(f"Severity:    {meta.severity.value.upper()}")
+        print(f"Summary:     {meta.short_description}\n")
+        print(f"Description:\n  {meta.full_description}\n")
+        print(f"Remediation:\n  {meta.remediation}\n")
+        if meta.references:
+            print("References:")
+            for ref in meta.references:
+                print(f"  - {ref}")
+        return 0
+
+    if args.command == "signatures":
+        sigs = load_signatures()
+        print(f"Loaded {len(sigs)} AI Action/CLI signatures:")
+        for sig in sigs:
+            actions = ", ".join(sig.action_prefixes) if sig.action_prefixes else "-"
+            bins = ", ".join(sig.cli_binaries) if sig.cli_binaries else "-"
+            print(f"  - {sig.id} ({sig.name} by {sig.vendor})")
+            print(f"      Actions: {actions} | CLIs: {bins}")
+        return 0
+
+    if args.command == "validate-signatures":
+        extra = [Path(d) for d in args.dirs]
+        try:
+            sigs = load_signatures(extra_dirs=extra)
+        except SignatureValidationError as exc:
+            print(f"✗ Signature validation failed: {exc}", file=sys.stderr)
+            return 1
+        print(f"✓ Successfully validated {len(sigs)} signature file(s).")
+        return 0
+
+    if args.command == "scan":
+        extra_dirs = [Path(d) for d in args.signatures_dir]
+        signatures = load_signatures(extra_dirs=extra_dirs)
+        files = _discover_workflow_files(args.paths)
+
+        # A security gate must not report success for files it never read
+        if not files:
+            print(f"Error: No workflow files found in: {', '.join(args.paths)}", file=sys.stderr)
+            return 2
+
+        if args.fix:
+            for wf in files:
+                modified, notes = apply_fixes_to_file(wf)
+                if modified:
+                    for note in notes:
+                        print(f"[FIXED] {wf.as_posix()}: {note}", file=sys.stderr)
+
+        min_sev = Severity(args.severity)
+        ignored = {r.upper() for r in args.ignore_rule}
+
+        all_findings: list[Finding] = []
+        unreadable: list[Path] = []
+        for wf in files:
+            try:
+                file_findings = scan_workflow_file(wf, signatures=signatures)
+            except (yaml.YAMLError, UnicodeDecodeError, OSError) as exc:
+                unreadable.append(wf)
+                print(f"Error: Could not scan {wf.as_posix()}: {exc}", file=sys.stderr)
+                continue
+            for f in file_findings:
+                if f.rule_id.upper() in ignored:
+                    continue
+                if f.severity.rank >= min_sev.rank:
+                    all_findings.append(f)
+
+        if args.format == "json":
+            output_text = format_json(all_findings)
+        elif args.format == "sarif":
+            output_text = format_sarif(all_findings)
+        elif args.format == "github":
+            output_text = format_github_annotations(all_findings)
+        else:
+            output_text = format_text(all_findings)
+
+        if args.output:
+            Path(args.output).write_text(output_text, encoding="utf-8")
+        elif output_text:
+            print(output_text)
+
+        if unreadable:
+            return 2
+
+        if args.fail_on == "none":
+            return 0
+        fail_sev = Severity(args.fail_on)
+        should_fail = any(f.severity.rank >= fail_sev.rank for f in all_findings)
+        return 1 if should_fail else 0
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

ci_agent_audit/fixer.py

@@ -0,0 +1,79 @@
+"""Deterministic auto-fix engine (`--fix`) for common AI CI/CD workflow misconfigurations."""
+
+from __future__ import annotations
+
+from pathlib import Path
+import re
+
+import yaml
+
+
+def apply_fixes_to_file(file_path: Path) -> tuple[bool, list[str]]:
+    """Apply safe, deterministic fixes to a workflow file and return (modified, applied_descriptions)."""
+    # Bytes keep the file's own line endings, which text mode would normalize on Windows
+    original = file_path.read_bytes().decode("utf-8")
+    updated, descriptions = apply_fixes_to_text(original)
+    if updated != original:
+        file_path.write_bytes(updated.encode("utf-8"))
+        return True, descriptions
+    return False, []
+
+
+def apply_fixes_to_text(content: str) -> tuple[str, list[str]]:
+    """Apply deterministic security remediations to workflow YAML text."""
+    descriptions: list[str] = []
+    text = content
+    newline = "\r\n" if "\r\n" in content else "\n"
+
+    # Fix 1 (AIA004): Upgrade vulnerable anthropics/claude-code-action versions (< 1.0.94)
+    # Branch refs are left alone: pinning @main to the safe minimum would be a large downgrade
+    def _upgrade_claude_action(match: re.Match[str]) -> str:
+        prefix = match.group(1)
+        ver = match.group(2)
+        cleaned = ver.lstrip("vV")
+        parts = cleaned.split(".")
+        if len(parts) == 3 and all(p.isdigit() for p in parts):
+            tup = (int(parts[0]), int(parts[1]), int(parts[2]))
+            if tup < (1, 0, 94):
+                descriptions.append(f"Upgraded vulnerable {prefix}@{ver} to @v1.0.94 (AIA004)")
+                return f"{prefix}@v1.0.94"
+        return match.group(0)
+
+    text = re.sub(
+        r"(anthropics/claude-code-action)@([A-Za-z0-9._-]+)",
+        _upgrade_claude_action,
+        text,
+    )
+
+    # Fix 2 (AIA003): Remove wildcard allowed_non_write_users / allowed_bots: "*"
+    wildcard_users_re = re.compile(
+        r"^([ \t]*(allowed_non_write_users|allowed_bots)[ \t]*:[ \t]*)(?:['\"]\*['\"]|\*)([ \t]*(?:#[^\r\n]*)?)(\r?)$",
+        re.MULTILINE,
+    )
+
+    def _clear_wildcard(match: re.Match[str]) -> str:
+        descriptions.append(f"Cleared insecure `{match.group(2)}: '*'` wildcard (AIA003)")
+        return f'{match.group(1)}""{match.group(3)} # Fixed by ci-agent-audit (AIA003){match.group(4)}'
+
+    text = wildcard_users_re.sub(_clear_wildcard, text)
+
+    # Fix 3 (AIA005): Replace `permissions: write-all` with least-privilege `contents: read`
+    write_all_re = re.compile(
+        r"^([ \t]*)permissions[ \t]*:[ \t]*['\"]?write-all['\"]?[ \t]*(?=\r?$)",
+        re.MULTILINE | re.IGNORECASE,
+    )
+
+    def _scope_permissions(match: re.Match[str]) -> str:
+        descriptions.append("Replaced `permissions: write-all` with `contents: read` (AIA005)")
+        indent = match.group(1)
+        return f"{indent}permissions:{newline}{indent}  contents: read"
+
+    text = write_all_re.sub(_scope_permissions, text)
+
+    # Never hand back a workflow that the fixes turned into invalid YAML
+    try:
+        yaml.safe_load(text)
+    except yaml.YAMLError:
+        return content, []
+
+    return text, descriptions

ci_agent_audit/formatters.py

@@ -0,0 +1,149 @@
+"""Output formatters for ci-agent-audit (text, json, sarif, github)."""
+
+from __future__ import annotations
+
+import json
+from typing import Iterable
+
+from ci_agent_audit import __version__
+from ci_agent_audit.models import Finding, Severity
+from ci_agent_audit.rules import RULES_CATALOG
+
+
+def format_text(findings: Iterable[Finding]) -> str:
+    """Format findings as human-readable terminal report."""
+    items = list(findings)
+    if not items:
+        return "✓ ci-agent-audit: 0 security issues found in scanned CI/CD workflows."
+
+    lines: list[str] = []
+    for f in items:
+        sev_badge = f"[{f.severity.value.upper()}]"
+        loc = f"{f.file_path.as_posix()}:{f.line}:{f.column}"
+        context = f" (job: {f.job_id})" if f.job_id else ""
+        lines.append(f"{sev_badge} {f.rule_id} ({f.rule_name}) at {loc}{context}")
+        lines.append(f"  Message:     {f.message}")
+        if f.snippet:
+            lines.append(f"  Snippet:     {f.snippet}")
+        lines.append(f"  Remediation: {f.remediation}")
+        lines.append("")
+
+    counts = {s: 0 for s in Severity}
+    for f in items:
+        counts[f.severity] += 1
+
+    summary_parts = [
+        f"{counts[Severity.CRITICAL]} critical",
+        f"{counts[Severity.HIGH]} high",
+        f"{counts[Severity.MEDIUM]} medium",
+        f"{counts[Severity.LOW]} low",
+    ]
+    lines.append(
+        f"✗ ci-agent-audit: Found {len(items)} issue(s) ({', '.join(summary_parts)})."
+    )
+    return "\n".join(lines)
+
+
+def format_json(findings: Iterable[Finding]) -> str:
+    """Format findings as structured JSON."""
+    items = [f.to_dict() for f in findings]
+    payload = {
+        "tool": "ci-agent-audit",
+        "version": __version__,
+        "total_findings": len(items),
+        "findings": items,
+    }
+    return json.dumps(payload, indent=2)
+
+
+def format_github_annotations(findings: Iterable[Finding]) -> str:
+    """Format findings as GitHub Actions workflow commands (`::error`, `::warning`, `::notice`)."""
+    lines: list[str] = []
+    for f in findings:
+        if f.severity in (Severity.CRITICAL, Severity.HIGH):
+            level = "error"
+        elif f.severity == Severity.MEDIUM:
+            level = "warning"
+        else:
+            level = "notice"
+
+        title = f"{f.rule_id} ({f.rule_name})"
+        escaped_msg = f.message.replace("%", "%25").replace("\r", "%0D").replace("\n", "%0A")
+        file_str = f.file_path.as_posix()
+        lines.append(
+            f"::{level} file={file_str},line={f.line},col={f.column},title={title}::{escaped_msg}"
+        )
+    return "\n".join(lines)
+
+
+def format_sarif(findings: Iterable[Finding]) -> str:
+    """Format findings as SARIF v2.1.0 for GitHub Code Scanning / Security tab."""
+    items = list(findings)
+    rules_list = []
+    for rule_id, meta in sorted(RULES_CATALOG.items()):
+        rules_list.append(
+            {
+                "id": rule_id,
+                "name": meta.name,
+                "shortDescription": {"text": meta.short_description},
+                "fullDescription": {"text": meta.full_description},
+                "help": {
+                    "text": f"{meta.full_description}\n\nRemediation: {meta.remediation}",
+                },
+                "defaultConfiguration": {"level": meta.severity.sarif_level},
+                "properties": {
+                    "tags": ["security", "ci-cd", "ai-agents", "prompt-injection"],
+                    "security-severity": _sarif_security_score(meta.severity),
+                },
+            }
+        )
+
+    results = []
+    for f in items:
+        results.append(
+            {
+                "ruleId": f.rule_id,
+                "level": f.severity.sarif_level,
+                "message": {"text": f"{f.message} Remediation: {f.remediation}"},
+                "locations": [
+                    {
+                        "physicalLocation": {
+                            "artifactLocation": {"uri": f.file_path.as_posix()},
+                            "region": {
+                                "startLine": max(1, f.line),
+                                "startColumn": max(1, f.column),
+                            },
+                        }
+                    }
+                ],
+            }
+        )
+
+    sarif_doc = {
+        "$schema": "https://json.schemastore.org/sarif-2.1.0.json",
+        "version": "2.1.0",
+        "runs": [
+            {
+                "tool": {
+                    "driver": {
+                        "name": "ci-agent-audit",
+                        "version": __version__,
+                        "informationUri": "https://github.com/layer8labs8/ci-agent-audit",
+                        "rules": rules_list,
+                    }
+                },
+                "results": results,
+            }
+        ],
+    }
+    return json.dumps(sarif_doc, indent=2)
+
+
+def _sarif_security_score(severity: Severity) -> str:
+    scores = {
+        Severity.CRITICAL: "9.5",
+        Severity.HIGH: "7.8",
+        Severity.MEDIUM: "5.5",
+        Severity.LOW: "3.0",
+    }
+    return scores[severity]

ci_agent_audit/models.py

@@ -0,0 +1,113 @@
+"""Data models for ci-agent-audit."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from pathlib import Path
+from typing import Any
+
+
+class Severity(str, Enum):
+    """Severity levels for audit findings."""
+
+    LOW = "low"
+    MEDIUM = "medium"
+    HIGH = "high"
+    CRITICAL = "critical"
+
+    @property
+    def rank(self) -> int:
+        ranks = {
+            Severity.LOW: 1,
+            Severity.MEDIUM: 2,
+            Severity.HIGH: 3,
+            Severity.CRITICAL: 4,
+        }
+        return ranks[self]
+
+    @property
+    def sarif_level(self) -> str:
+        if self in (Severity.HIGH, Severity.CRITICAL):
+            return "error"
+        if self == Severity.MEDIUM:
+            return "warning"
+        return "note"
+
+
+@dataclass(frozen=True)
+class RuleMetadata:
+    """Definition of a built-in security rule."""
+
+    rule_id: str
+    name: str
+    severity: Severity
+    short_description: str
+    full_description: str
+    remediation: str
+    references: list[str] = field(default_factory=list)
+
+
+@dataclass(frozen=True)
+class DangerousFlagPattern:
+    """A CLI flag or input argument pattern that enables unsafe agent execution."""
+
+    pattern: str
+    reason: str
+
+
+@dataclass(frozen=True)
+class ActionSignature:
+    """Declarative signature for an AI GitHub Action or CLI tool (1 YAML file per tool)."""
+
+    id: str
+    name: str
+    vendor: str
+    description: str
+    action_prefixes: list[str] = field(default_factory=list)
+    non_agent_actions: list[str] = field(default_factory=list)
+    cli_binaries: list[str] = field(default_factory=list)
+    cli_packages: list[str] = field(default_factory=list)
+    cli_subcommands: list[str] = field(default_factory=list)
+    prompt_inputs: list[str] = field(default_factory=list)
+    cli_prompt_flags: list[str] = field(default_factory=list)
+    dangerous_inputs: dict[str, str] = field(default_factory=dict)
+    dangerous_arg_patterns: list[DangerousFlagPattern] = field(default_factory=list)
+    min_safe_version: str | None = None
+    advisory_url: str | None = None
+    source_file: str | None = None
+
+
+@dataclass
+class Finding:
+    """A security issue detected in a CI/CD workflow file."""
+
+    rule_id: str
+    rule_name: str
+    severity: Severity
+    file_path: Path
+    line: int
+    column: int
+    message: str
+    remediation: str
+    job_id: str | None = None
+    step_name: str | None = None
+    snippet: str | None = None
+    tool_id: str | None = None
+    extra: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "rule_id": self.rule_id,
+            "rule_name": self.rule_name,
+            "severity": self.severity.value,
+            "file": str(self.file_path.as_posix()),
+            "line": self.line,
+            "column": self.column,
+            "job_id": self.job_id,
+            "step_name": self.step_name,
+            "tool_id": self.tool_id,
+            "message": self.message,
+            "remediation": self.remediation,
+            "snippet": self.snippet,
+        }