Metadata-Version: 2.4
Name: pace-agents
Version: 0.1.0
Summary: Compliance audit CLI: AST pattern matching + LLM agent loop + autonomous fix generation + audit-ready evidence
Project-URL: Homepage, https://pace.watch
Project-URL: Repository, https://github.com/01x-in/pace-agents
Project-URL: Issues, https://github.com/01x-in/pace-agents/issues
Author: PACE
License: MIT
License-File: LICENSE
Keywords: audit,cli,compliance,hipaa,pci-dss,security,soc2
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.11
Requires-Dist: cryptography>=42.0.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: openai>=1.30.0
Requires-Dist: pydantic>=2.7.0
Requires-Dist: pyyaml>=6.0.1
Requires-Dist: rich>=13.7.0
Requires-Dist: tomli-w>=1.0.0
Requires-Dist: tree-sitter-python>=0.21.0
Requires-Dist: tree-sitter>=0.22.0
Requires-Dist: typer>=0.12.0
Description-Content-Type: text/markdown

# PACE

> Find every compliance violation in your codebase, auto-fix them with verified patches, and generate the audit-ready evidence trail that proves it — without hiring a security consultant.

---

## Install

PACE ships as the `pace-agents` Python package and exposes the `pace` CLI.

```bash
# Recommended for local CLI use
pipx install pace-agents

# Standard Python install
pip install pace-agents

# Homebrew tap
brew install 01x-in/tap/pace-agents
```

After installing, run:

```bash
pace --help
pace init --profile hipaa
```

---

## What is PACE?

PACE is a CLI tool for engineering teams that need to demonstrate code-level compliance — HIPAA, SOC2, PCI-DSS — without a dedicated security team. It combines a two-pass audit loop with a four-agent fix loop to go from raw codebase to timestamped evidence artifact in a single workflow.

**Snyk finds. PACE finds, fixes, and proves.**

---

## How it works

### Step 1 — Initialize

```bash
pace init --profile hipaa
```

Select your compliance framework (`hipaa`, `soc2`, `pci-dss`, or `all`) and configure your LLM endpoint in `pace.toml`. Pass 1 scanning works entirely offline with no LLM calls — pure AST pattern matching, always free.

### Step 2 — Scan

```bash
pace scan
```

Runs a two-pass audit of your codebase:

- **Pass 1** — tree-sitter AST pattern matching against the YAML rule library. Deterministic, no LLM, zero cost. Runs in CI too.
- **Pass 2** — an autoresearch-style agent loop that walks every function in the code index, reviewing each one for compliance violations with an accumulated audit journal. Review 47 knows what reviews 1–46 found — this is how PACE catches violations that span multiple files.

### Step 3 — Fix

```bash
pace fix
```

Runs the four PACE agents on open findings (see below).

### Step 4 — Report

```bash
pace report
```

Generates three timestamped evidence artifacts in `.pace/`:

| File | Use |
|---|---|
| `report-<ts>.md` | Markdown — for developers and version control |
| `report-<ts>.json` | JSON — for CI pipelines and tooling |
| `report-<ts>.html` | HTML — self-contained, auditor-readable, open in any browser |

Each finding is mapped to its specific compliance control (e.g., HIPAA §164.312(a)(1), PCI-DSS Req 3.4, SOC2 CC6.1). The HTML report includes color-coded severity and status badges, syntax-highlighted before/after diffs, and Evaluator verdict for every fixed finding.

---

## The Four PACE Agents

PACE is an acronym. The fix loop runs four specialist agents sequentially — the output of each becomes the input of the next. Each agent has a single, focused job, and can be retried independently on failure.

```
Planner → [for each finding group]:
  Author → Coder → Evaluator
    ↑_______________|  (on reject, up to N retries)

After retry cap:  finding → needs-human-review
After accept:     finding → fixed, patch staged, evidence recorded
```

### P — Planner

Receives the complete audit journal and the full list of open findings. Ranks violations by severity and compliance framework weight, then clusters related findings that share a root cause or fix strategy (e.g., multiple PHI-in-logs violations stemming from the same logging utility).

- **Input:** Audit journal + open findings list
- **Output:** Ordered fix plan with severity rankings and fix strategy hints
- **Does NOT:** Write code, apply patches, or validate anything

### A — Author

Receives a single finding group from the Planner, the relevant functions from the code index, and any fix strategy hint. Proposes a concrete code patch — not a general suggestion, but a specific diff. On retry, receives the Evaluator's failure context and must revise its proposal.

- **Input:** Finding group + relevant code + fix strategy hint (+ failure context on retry)
- **Output:** Proposed code patch (diff)
- **Does NOT:** Apply the patch or run tests

### C — Coder

Receives the Author's proposed patch and applies it to a feature branch, then runs the project's existing test suite against the patched branch. Purely mechanical — applies the patch, runs the tests, reports results.

- **Input:** Proposed patch + branch ref
- **Output:** Patch application status + test suite results (pass/fail counts, failure output)
- **Does NOT:** Judge correctness, re-scan for compliance, or interpret test failures

### E — Evaluator

The acceptance gate. Re-runs the compliance scan on the patched branch, checking that (1) tests pass, (2) the original finding is gone, and (3) no new violations were introduced. A fix is accepted only if all three conditions hold. On rejection, returns structured failure context to the Author for retry. After the retry cap (default: 3), the finding is flagged `needs-human-review` and the loop moves on.

- **Input:** Test results + patched branch
- **Output:** Accept or reject decision + structured failure context (on reject)
- **Does NOT:** Write code or propose alternatives — only accepts or rejects

---

## What PACE scans for

Three categories across all compliance profiles:

| Category | Examples |
|---|---|
| Sensitive data flow | PII/PHI/cardholder data in logs, error handlers, API responses, debug outputs |
| Supply chain integrity | Post-install hooks, obfuscated payloads, base64 execution in transitive dependencies |
| Secrets & credential hygiene | Hardcoded keys, unrotated tokens, permissive configs |

The compliance profile is a config layer that determines which rules are prioritized and which framework controls appear in the evidence output — same detection engine, different audit language.

---

## Rulesets

Rule packs are distributed separately from the PACE engine — install only what your audit requires.

```bash
# See what's installed and what's available
pace rules ls

# Install a pack
pace rules install hipaa
pace rules install hipaa --global   # install to ~/.pace/rulesets/ (shared across projects)

# Keep packs up to date
pace rules update
pace rules update hipaa
```

`pace rules ls` shows installed packs alongside all available packs from pace.watch:

```
Installed packs
────────────────────────────────────────────────────────────────────────────────
  PROFILE      TIER         VERSION    SCOPE      PATH
  hipaa        community    1.2.0      global     ~/.pace/rulesets/hipaa/...

Available packs
────────────────────────────────────────────────────────────────────────────────
  PROFILE      DESCRIPTION
  soc2         SOC 2 Type II — availability, confidentiality, change management
  pci-dss      PCI DSS v4.0 — cardholder data, transmission security, authentication
  gdpr         GDPR — personal data exposure, consent signals, data minimisation
  nist         NIST CSF — identify, protect, detect, respond, recover controls
  iso27001     ISO 27001 — information security management system controls

  Visit pace.watch/rules for expert-reviewed rulesets — HIPAA, SOC2, GDPR and more.
```

Each rule is tagged with a universal category (`encryption`, `secrets-credentials`, `audit-logging`, etc.) that works across frameworks — so a `--category encryption` filter surfaces all encryption gaps regardless of whether the finding came from HIPAA, PCI-DSS, or NIST rules.

---

## CI integration

```bash
pace scan --diff HEAD~1 --pass1-only
```

Scans only changed files using Pass 1 (AST pattern matching only — no LLM calls) and exits non-zero on new violations. Drop it in your PR checks to block merges that introduce compliance regressions.

> Without `--pass1-only`, `pace scan` also runs Pass 2 (the LLM audit loop) and requires a configured LLM endpoint.

---

## Key design decisions

- **Zero vendor lock-in** — bring your own LLM endpoint via `pace.toml` (OpenRouter, Ollama, vLLM, any OpenAI-compatible provider). PACE never hardcodes a provider.
- **Privacy controlled by you** — your code never leaves your machine unless you point PACE at a remote endpoint. Use Ollama (`http://localhost:11434/v1`) for fully local LLM inference, vLLM on your own GPU, or any OpenAI-compatible provider. Pass 1 (AST scanning) is always local and always free — no LLM required.
- **BYOE (Bring Your Own Endpoint)** — no provider is hardcoded. Configure any OpenAI-compatible endpoint in `pace.toml`: Ollama, vLLM, OpenRouter, Azure OpenAI. Air-gapped healthcare environments can run Pass 1 fully offline and Pass 2 with a local Ollama instance.
- **Content-hash finding IDs** — findings survive code refactoring without false regressions.
- **Bounded context** — the audit loop uses compressed journal summaries, not full review transcripts. Works on codebases of any size.
- **Delta audits** — `.pace/audit-state.json` persists finding status across runs; only new or regressed findings re-enter the loops.

---

## Tech stack

- Python CLI via [typer](https://typer.tiangolo.com/)
- Code indexing: [codeindex](https://github.com/01x-in/codeindex) (Go binary, tree-sitter → SQLite) — installed separately
- LLM integration: single OpenAI-compatible client
- Rule library: YAML rule packs distributed via pace.watch — install with `pace rules install <profile>` (not bundled in the pip package)
- Audit state: `.pace/audit-state.json` committed to repo
- Evidence output: structured markdown for developers, JSON for CI pipelines
- Install: `pipx install pace-agents` — then `pace rules install hipaa` to pull the rule pack

---

## Compared to alternatives

| Tool | Finds violations | Auto-fixes | Compliance-mapped evidence |
|---|---|---|---|
| Vanta / Drata | infra & policy only | — | — |
| Snyk / Semgrep | yes | no | no |
| **PACE** | **yes** | **yes** | **yes** |

---

*Built by [01x](https://01x.in)*
