agentci-guard 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 David Wu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,144 @@
+# AgentCI Guard
+
+AgentCI Guard is a CLI and GitHub Action that detects unsafe AI coding-agent usage in CI/CD workflows.
+
+It focuses on one high-risk pattern: untrusted GitHub event content reaching an AI agent that has secrets, write permissions, shell access, or unsafe checkout behavior.
+
+![AgentCI Guard scanning a vulnerable workflow](docs/demo.svg)
+
+> The animated terminal demo is generated from [`docs/demo.tape`](docs/demo.tape) — run `vhs docs/demo.tape` to produce `docs/demo.gif`.
+
+## What It Detects
+
+- AI-agent usage in `.github/workflows/*.yml`
+- `pull_request_target` combined with AI agents
+- PR/issue/comment/review/branch/commit content passed into prompts or shell commands
+- `contents: write`, `pull-requests: write`, or other broad write scopes near AI usage
+- `secrets.*`, `GITHUB_TOKEN`, and token-like environment variables in agent jobs
+- shell access combined with AI usage
+- unpinned third-party AI actions
+- checkout of untrusted PR head code in privileged contexts
+
+## CLI Quickstart
+
+```bash
+# Run without installing
+npx agentci-guard scan .
+
+# Or install globally
+npm install -g agentci-guard
+
+agentci scan .
+agentci scan . --json
+agentci scan . --sarif agentci-results.sarif
+agentci explain agentci/untrusted-ai-write-token
+```
+
+Exit codes:
+
+- `0`: no findings at or above `--fail-on`
+- `2`: at least one finding at or above `--fail-on`
+- `1`: scanner error
+
+Default fail threshold is `high`.
+
+## GitHub Action
+
+```yaml
+name: agentci-guard
+on: [pull_request, push]
+
+permissions:
+  contents: read
+  security-events: write
+
+jobs:
+  scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: David-Wu1119/agentci-guard@v0
+        with:
+          path: .
+          sarif: agentci-results.sarif
+          fail-on: high
+      - uses: github/codeql-action/upload-sarif@v3
+        if: always()
+        with:
+          sarif_file: agentci-results.sarif
+```
+
+### Outputs
+
+The action sets `findings`, `critical`, `high`, `medium`, `low`, and `sarif-path` so later steps can react:
+
+```yaml
+      - uses: David-Wu1119/agentci-guard@v0
+        id: agentci
+        with:
+          fail-on: none
+      - if: steps.agentci.outputs.critical != '0'
+        run: echo "::warning::${{ steps.agentci.outputs.critical }} critical finding(s)"
+```
+
+If `agentci.config.json` exists in the scanned path it is picked up automatically (see [Suppressing Findings](#suppressing-findings)).
+
+## Example Finding
+
+```text
+CRITICAL agentci/untrusted-ai-write-token
+File: .github/workflows/ai-agent.yml / job: claude
+Evidence: untrusted trigger + AI usage + write permissions + untrusted GitHub event context
+
+Why:
+An attacker can place prompt-injection text in a PR, issue, or comment. If that text reaches an AI agent with repository write permissions, the agent can be induced to modify code, comments, workflows, or releases.
+
+Fix:
+- Do not run privileged AI agents on untrusted triggers.
+- Use read-only GITHUB_TOKEN permissions for untrusted events.
+- Require maintainer approval before running the agent.
+- Sanitize and summarize untrusted content before passing it to an agent.
+```
+
+## Suppressing Findings
+
+Real workflows sometimes have a finding you've reviewed and accepted. Two ways to silence one without disabling the whole scan:
+
+**Inline (per file)** — add a comment anywhere in the workflow:
+
+```yaml
+# agentci-ignore agentci/unpinned-ai-action -- mirrored internally, reviewed 2026-06
+# agentci-ignore-all                          -- silence every rule in this file
+```
+
+**Config file** — `agentci.config.json` in the scanned path (or pass `--config <path>`):
+
+```json
+{
+  "ignore": ["agentci/unpinned-ai-action"],
+  "ignorePaths": ["**/generated-*.yml"]
+}
+```
+
+`ignore` suppresses a rule everywhere; `ignorePaths` excludes matching workflow files (`*` within a path segment, `**` across segments). Ignored files are still parsed — they just don't report findings.
+
+## Development
+
+```bash
+corepack enable
+pnpm install
+pnpm typecheck
+pnpm test
+pnpm build
+npm pack --dry-run
+```
+
+## Security Boundary
+
+AgentCI Guard is a static scanner. It does not sandbox workflows or prove that an agent is safe. It identifies high-risk patterns that should receive human review before AI agents are allowed to run with privileged CI/CD context.
+
+See [Threat Model](docs/threat-model.md) and [Real-World Findings](docs/real-world-findings.md) (a scan of 75 public repos that run AI agents in CI).
+
+## License
+
+MIT

package/SECURITY.md

@@ -0,0 +1,23 @@
+# Security Policy
+
+AgentCI Guard is security-sensitive CI/CD tooling. Do not publish exploit details for unfixed vulnerabilities in public issues.
+
+## Supported Versions
+
+During the `0.x` phase, only the latest `main` branch and latest published package are supported.
+
+## Reporting a Vulnerability
+
+Use GitHub Security Advisories when available. If private reporting is unavailable, open a minimal public issue asking for a disclosure channel without including exploit details.
+
+A useful report includes:
+
+- AgentCI Guard version or commit
+- Workflow YAML that reproduces the issue, with secrets removed
+- Expected finding
+- Actual finding
+- Whether the issue is false negative, false positive, crash, or SARIF/report problem
+
+## Non-Goals
+
+AgentCI Guard does not execute or sandbox workflows. A static scan passing does not certify an AI-agent workflow as safe.

package/action.yml

@@ -0,0 +1,42 @@
+name: AgentCI Guard
+description: Scan GitHub Actions workflows for unsafe AI coding-agent usage.
+author: David Wu
+branding:
+  icon: shield
+  color: red
+inputs:
+  path:
+    description: Repository path to scan.
+    required: false
+    default: "."
+  sarif:
+    description: SARIF output path.
+    required: false
+    default: "agentci-results.sarif"
+  fail-on:
+    description: Minimum severity that fails the action. One of none, low, medium, high, critical.
+    required: false
+    default: "high"
+outputs:
+  findings:
+    description: Total number of findings.
+  critical:
+    description: Number of critical-severity findings.
+  high:
+    description: Number of high-severity findings.
+  medium:
+    description: Number of medium-severity findings.
+  low:
+    description: Number of low-severity findings.
+  sarif-path:
+    description: Path to the written SARIF file.
+runs:
+  using: node24
+  main: dist/cli.js
+  args:
+    - scan
+    - ${{ inputs.path }}
+    - --sarif
+    - ${{ inputs.sarif }}
+    - --fail-on
+    - ${{ inputs.fail-on }}

package/dist/cli.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node