Usage¶

Prerequisites¶

Set OPENAI_API_KEY or ANTHROPIC_API_KEY before running scan
Place .aion.yaml in the target repository root if you want policy or sandbox defaults
Use --output json when you want machine-readable artifacts

1. Scan a repository¶

uv run aion scan ./path/to/project

Scan only files you already know are AI-generated:

uv run aion scan ./path/to/project \
  --ai-generated ./path/to/project/generated_file.py

Switch provider or emit JSON:

uv run aion scan ./path/to/project --provider openai --output json

Print extracted context, fallback reasons, and Semgrep detail:

uv run aion scan ./path/to/project --verbose

2. Generate and verify a repair artifact¶

Create a deterministic patch artifact and persist the audit trail:

uv run aion repair ./path/to/file.py \
  --context-file ./context.json \
  --artifact-path ./artifact.json \
  --record-path ./repair-record.json

Verify an existing artifact:

uv run aion verify --artifact-path ./artifact.json

Run the full incident flow against a single file:

uv run aion run-incident ./path/to/file.py \
  --context-file ./context.json \
  --record-path ./incident-record.json \
  --output json

Evaluate deterministic repair quality across fixtures:

uv run aion repair-eval ./tests/fixtures \
  --records-dir ./repair-records \
  --output json

3. Orchestrate events in a sandbox¶

Process one event:

uv run aion process-event ./event.json \
  --result-path ./orchestration.json \
  --output json

Process a JSON array of events:

uv run aion process-event-queue ./events.json \
  --results-dir ./queue-results \
  --output json

Typical event payload:

{
  "event_id": "runtime-001",
  "event_type": "runtime_alert",
  "target_file": "/absolute/path/to/service.py",
  "metadata": {
    "repo_root": "/absolute/path/to/repo",
    "context_file": "/absolute/path/to/context.json"
  }
}

Supported event types in the current release:

code_scan
runtime_alert
dependency_alert

4. Use the persistent inbox and webhook¶

Enqueue an event into the file-backed inbox:

uv run aion enqueue-event ./event.json \
  --inbox-root ./.aion/inbox

Inspect pending or processed items:

uv run aion list-inbox \
  --inbox-root ./.aion/inbox \
  --status pending

Process everything currently pending:

uv run aion process-inbox \
  --inbox-root ./.aion/inbox \
  --output json

Start the webhook receiver:

uv run aion serve-webhook \
  --inbox-root ./.aion/inbox \
  --host 127.0.0.1 \
  --port 8080

The webhook accepts POST /events and writes accepted payloads into the inbox.

5. Manage staged rollout¶

Create a release candidate from a successful orchestration result:

uv run aion create-release-candidate ./.aion/inbox/results/<event>.json \
  --releases-root ./.aion/releases

Inspect current candidates:

uv run aion list-releases --releases-root ./.aion/releases

Approve and advance through phases:

uv run aion approve-release <candidate-id> \
  --approver alice \
  --releases-root ./.aion/releases

uv run aion advance-release <candidate-id> \
  --releases-root ./.aion/releases

Reject or roll back:

uv run aion reject-release <candidate-id> \
  --approver alice \
  --reason "review failed" \
  --releases-root ./.aion/releases

uv run aion rollback-release <candidate-id> \
  --reason "failed canary metrics" \
  --releases-root ./.aion/releases

6. Plan runtime defense actions¶

Generate containment recommendations from an orchestration result:

uv run aion plan-defense ./.aion/inbox/results/<event>.json --output json

The current defense planner can emit:

gateway blocks
WAF rules
feature flag actions
dependency pin recommendations
code-patch follow-up actions

7. Auto-Update¶

Run the full scan → fix → PR pipeline:

uv run aion auto-update --target ./

Dry-run to inspect what would happen without creating PRs:

uv run aion auto-update --target ./ --dry-run

The auto-update command:

Reads .aion.yaml for scheduling, policy, and PR configuration
Scans all Python files for security incidents
Generates deterministic patches for supported issue types
Verifies each patch in an isolated workspace
Creates a pull request for each verified fix
Respects open_pull_requests_limit to avoid PR floods

GitHub Action¶

AION ships with a reusable GitHub Action (action.yml). Add to your workflow:

- uses: shenxianpeng/aion@main
  with:
    target: '.'
  env:
    OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}

Or schedule it with GitHub Actions:

name: AION Auto-Update
on:
  schedule:
    - cron: '0 9 * * 1'  # Weekly on Monday at 09:00 UTC
  workflow_dispatch:

permissions:
  contents: write
  pull-requests: write

jobs:
  auto-update:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: shenxianpeng/aion@main

8. Track security drift and evolution¶

Save a security baseline¶

Capture the current security state of your repository:

uv run aion snapshot ./src --name baseline

This creates .aion/snapshots/baseline.json containing a health score, incident list, and file hashes — a reproducible fingerprint of the repository's security posture.

Check for drift¶

Compare the current state against a saved snapshot to detect regressions:

uv run aion drift ./src --name baseline

Exit code 0 means no regression. Exit code 1 means new incidents were found. Use --output json to get a machine-readable drift report for CI integration.

Continuous watch mode¶

Monitor a directory for security drift and auto-repair new incidents as they appear:

uv run aion watch ./src --interval 30 --auto-repair

AION polls every --interval seconds, compares against the last known-good baseline, and automatically generates and verifies patches for any new incidents. When a repair reaches verified_fix, watch writes the patched content back to the watched local file and refreshes the baseline. Each successful repair is recorded in the knowledge base so future runs improve.

Inspect engine health and learned patterns¶

Show accumulated snapshots and knowledge-base repair patterns:

uv run aion status
# or specify a custom .aion directory
uv run aion status --aion-dir ./.aion --output json

9. Operational notes¶

The current release emits patch artifacts and watch can rewrite watched local files after verification; it does not rewrite live production files in place.
sandbox_verification_commands run inside the staged workspace, not inside your working tree.
process-event and inbox processing automatically load .aion.yaml from the event repository root.
repair-eval reports repair success rate, verification pass rate, false-fix rate, and rollback rate.
Drift snapshots and knowledge-base patterns are persisted in .aion/ and survive restarts.