🛡️ ActionGuard AutoAudit

Detection  ➔  Evidence  ➔  Severity  ➔  Suggested Fix  ➔  Patch Preview  ➔  HTML Report

---

ActionGuard extends zizmor with agentic workflow-injection detection, committed secret redaction, artifact upload security checks, multi-scanner integrations, normalized risk scoring, and interactive HTML/JSON reporting.

---

⚡ Quick Start

# Set up virtual environment and install ActionGuard
python -m venv .venv && source .venv/bin/activate
pip install -e '.[dev]' zizmor

# Run security audit on current repository
actionguard audit . --html reports/actionguard-report.html --json reports/actionguard-report.json

Note: Missing optional scanners fail gracefully without breaking the audit run.

---

🤖 5 Agentic AI Workflow Security Rules

Rule ID	Name	Threat Category	Description
AG-AI-001	Issue Comment Trigger	Untrusted Trigger	Detects issue_comment triggers vulnerable to prompt injection
AG-AI-002	Write-All Permissions	Excessive Privilege	Flags permissions: write-all on AI workflow runners
AG-AI-003	Unescaped Input in Shell	Shell Injection	Identifies unescaped ${{ github.event.comment.body }} in run:
AG-AI-004	Dynamic Script Execution	Code Execution	Detects AI generating and executing temporary shell scripts
AG-AI-005	Secret Injected to AI	Credential Exposure	Flags secrets passed to untrusted AI agent execution context

---

📊 Pipeline Architecture & Workflow

%%{init: {'theme': 'dark', 'themeVariables': { 'primaryColor': '#1e293b', 'edgeLabelBackground':'#0f172a'}}}%%
flowchart TD
    Trigger["🚀 GitHub Push / PR Event"] --> Checkout["📦 Checkout Repository"]
    Checkout --> Orchestrator["🛡️ ActionGuard Engine"]
    
    subgraph Scanners["Scanners & Audit Modules"]
        direction TB
        Zizmor["zizmor GitHub Actions Scanner"]
        AgenticRules["5 Custom Agentic AI Rules"]
        SecretAudit["Secret Redaction Audit"]
        ArtifactAudit["Artifact Retention Audit"]
        CodeQuality["Ruff & Bandit Integration"]
    end
    
    Orchestrator --> Scanners
    Scanners --> Findings["📋 Normalized Findings"]
    Findings --> Scoring["📈 Risk Scoring (0-100)"]
    Scoring --> Remediation["🔧 Patch & Remediation Plan"]
    Remediation --> OutputJSON["📄 actionguard-report.json"]
    Remediation --> OutputHTML["📊 actionguard-report.html"]

Loading

---

🛠️ Security Rules & Multi-Scanner Integration

%%{init: {'theme': 'dark'}}%%
graph LR
    Core["🛡️ ActionGuard Engine"] --> Native["Built-in Security Scanners"]
    Core --> External["External Security Scanners"]

    Native --> R1["Agentic AI Workflow Audit"]
    Native --> R2["Env & Secret Exposure"]
    Native --> R3["Artifact Upload Security"]
    Native --> R4["Repository Hygiene"]

    External --> E1["zizmor (Actions Security)"]
    External --> E2["Ruff (Python Linter)"]
    External --> E3["Bandit (Code Security)"]
    External --> E4["npm audit & pip-audit"]

Loading

---

💻 Available CLI Commands (Click to expand)

# Complete audit (HTML + JSON report)
actionguard audit .

# Alias for audit
actionguard scan .

# Re-render HTML from an existing JSON report
actionguard report --json actionguard-report.json --html actionguard-report.html

# Run via python module
python -m actionguard.cli audit . --html report.html --json report.json

Add --email to send HTML reports via SMTP when MAIL_USERNAME, MAIL_PASSWORD, and REPORT_TO_EMAIL environment variables are configured.

🔒 Safety & Redaction Model (Click to expand)

• Secret Redaction: Credentials are automatically truncated to first six characters followed by ...redacted.
• Scan Safeguards: Skips binary files, files > 1 MB, and build output directories (node_modules, .venv, dist).
• Non-destructive: ActionGuard never deletes .env files, rotates keys, or alters repository permissions automatically.

🧪 Demo & Test Fixtures (Click to expand)

# Run audit on demo vulnerable repository
actionguard audit examples/demo-vulnerable-repo \
  --html reports/demo-report.html --json reports/demo-report.json

# Run unit test suite
pytest -q

---

🤝 Contributing

Contributions are very welcome! Whether it's adding new security rules, improving report visualizations, or integrating additional static analysis scanners:

1. Check out our Contributing Guide for local setup and testing instructions.
2. Open an issue or pull request using our templates.

---

📜 Upstream Attribution & License

ActionGuard uses zizmor as its core GitHub Actions scanner integration under its upstream license. See NOTICE.md.

Distributed under the MIT License.