Rung — AI Agent Governance Audit

Know how much authority to give coding agents before they touch your repository.

Rung evaluates 11 repository-evidence checks informed by NIST AI RMF, agents.md, SLSA, and published engineering practices. It uses a six-state evidence maturity model (absent, claimed, detected, enforced, verified, unobservable), then reports a repository governance-evidence score, quality gate, maximum recommended agent authority, and actionable next steps.

Quick start

# Clone
git clone https://github.com/edoworks/rung.git
cd rung

# Run against your repo
python3 -m rung --root /path/to/your/repo

# JSON output for CI
python3 -m rung --root /path/to/your/repo --json

# Dependency-free standalone artifact
python3 rung-cli.py --root /path/to/your/repo --json

The original rung --root ... invocation remains the normal audit interface.

Reproducible receipts

Run Rung from an independently installed, version-pinned distribution. Do not install or execute code from the repository being audited. Both output paths must be outside their audited checkout and must not already exist.

# Create canonical RungVerificationReceipt/v1 evidence.
rung verify --root /path/to/clean-checkout --receipt /safe/outside/receipt.json

# Re-run from a separate clean checkout and write a distinct observation.
rung replay --root /path/to/independent-clean-checkout \
  --receipt /safe/outside/receipt.json \
  --observation /safe/outside/observation.json

verify requires an exact clean Git HEAD, including no untracked files, a supported GitHub origin, and no tracked symlinks or submodules. Every regular tracked file is compared with its HEAD blob even when index flags hide changes; the audit reads only verified Git objects materialized into a private directory. HTTPS, SCP-style SSH, and ssh:// GitHub origins normalize to the lowercase identity github.com/owner/repository. The receipt binds that identity, the commit and tree object IDs, UTC Git committer timestamp, AuditResult schema and digest, gate, authority, Rung version, engine identity, stable structured arguments, and limitations.

Receipt and observation files are strict, canonical UTF-8 JSON. Unknown or duplicate members, noncanonical hashes, invalid fields, and inputs over 1 MiB are rejected. Each document has a SHA-256 digest computed over canonical JSON excluding its own digest member. Replay never changes the receipt. It returns 0 for a match, 2 for structurally valid evidence that does not match, and 1 for malformed input or a runtime failure. A valid mismatch still produces an immutable replay observation with deterministic mismatch categories; malformed input produces no trusted observation.

The engine_artifact_sha256 bytes are defined precisely as the standalone generator's bundled-source stream: for every rung/**/*.py in sorted path order, UTF-8 encode its normalized module name, NUL, LF-normalized UTF-8 source, and NUL. The generated rung-cli.py recomputes this digest from the actual read-only source map its loader executes; modular installs compute the same value from installed package sources.

What it checks

Total: 100 points (file-size discipline is non-scoring). Quality gate passes only if all blocking checks reach at least detected state.

Evidence states

Every check returns one of six evidence states instead of boolean pass/fail:

Authority recommendations

Based on evidence states, Rung recommends a maximum agent authority:

Scoring

Install

From source

git clone https://github.com/edoworks/rung.git
cd rung
python3 -m rung --root .

Package registry

The release workflow is configured to publish tagged releases to PyPI through GitHub Actions OIDC Trusted Publishing. For a version observed on PyPI, install the exact version rather than an unbounded dependency:

python3 -m pip install "rung-audit==0.3.1"

If that version is not yet visible on PyPI, install from a pinned source revision or use the standalone artifact. A Git tag or workflow run alone is not proof that registry publication succeeded.

Standalone artifact

rung-cli.py is generated from the canonical modular package and runs with Python 3.10+ without installation or third-party dependencies. Contributors must regenerate and verify it after changing rung/:

python3 scripts/build_single_file.py
python3 scripts/build_single_file.py --check

The generator embeds a digest of all package sources and emits deterministic bytes. Do not edit rung-cli.py directly.

Release validation

Contributors can build and validate the complete release artifact set locally:

python3 scripts/validate_release.py --dist dist

Agent skill

Install the reproducible-verification workflow with the skills CLI:

npx skills add edoworks/rung --skill rung-reproducible-verification

The skill requires an independently installed, pinned Rung engine, a receipt from one clean checkout, and replay from another. Canonical JSON, not generated model prose, is the authoritative evidence.

Use in CI

Rung's GitHub Action is planned but not yet published to Marketplace. After a tagged release, pin the action to a release tag or commit SHA and use its read-only interface:

- uses: edoworks/rung@v0.3.1
  with:
    minimum-score: 70
    require-gate: true

Receipt creation and replay require descriptor-relative filesystem semantics and therefore fail closed on native Windows. Repository audits remain supported on Windows; use Linux, macOS, or WSL for receipt mode.

For source-based CI before publication:

# .github/workflows/governance-audit.yml
name: Governance Audit
on: [pull_request]
jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Setup Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      - name: Run Rung governance audit
        run: |
          pip install .
          python3 -m rung --root . --json > audit.json
          SCORE=$(python3 -c "import json; print(json.load(open('audit.json'))['score'])")
          echo "Governance score: $SCORE/100"
          if [ "$SCORE" -lt 70 ]; then echo "::error::Governance score below threshold (70)"; exit 1; fi

Cited sources

Rung is informed by standards and industry practices. Not every check is directly derived from a standard.

• agents.md — Linux Foundation / AAIF cross-vendor agent policy spec
• GitHub Copilot repository custom instructions
• NIST AI Risk Management Framework 1.0
• Anthropic — How we built our multi-agent research system
• openai/codex AGENTS.md — 500/800 LoC thresholds
• apache/airflow AGENTS.md — Generated-by attribution, Never-rules
• IBM — Agent Development Lifecycle
• SLSA v1.2 — Supply-chain Levels for Software Artifacts
• ISO/IEC 42001:2023 — AI management system standard
• OpenSSF Scorecard — Check-specific risk explanation model

Limitations

A public, accountless scan cannot inspect some important enforcement settings. GitHub's branch-protection API requires Administration read permission, even for reads on public repositories. Rung therefore labels these controls as unobservable rather than passing or failing them.

Rung's production audit is a deterministic, non-LLM scanner and does not install or execute target-repository code. It remains an automated public-only evidence assessment: unobservable controls and resulting authority limits are preserved in receipts and replay observations. Unsigned reproducibility evidence is not attestation, certification, enforcement proof, correctness proof, compliance, or legal advice.

Sponsor

If Rung helps your team, consider supporting Edoworks OSS.

License

MIT