# Community test suites

`agentsec suite ...` lets you install third-party AgentSec test suites
contributed by the community. Bundles live in third-party GitHub
repositories; a curated index in this repo at
`src/agentsec/suite_registry/community-suites.yaml` is the trust anchor.

## Commands

```bash
agentsec suite list                 # browse what's available
agentsec suite info <name>          # show the manifest of an installed suite
agentsec suite install <name>       # install + verify + land in ~/.agentsec/suites/
agentsec suite uninstall <name>     # remove the local copy
```

`agentsec run --suite <name>` runs an installed suite the same way
`agentsec run <path>` runs a directory.

## Installation flow

```
agentsec suite install <name>
  → registry lookup
  → fetch tarball from github.com via codeload.github.com
  → extract to a temp dir (PEP-706 data filter — no path traversal)
  → canonical SHA-256 of the bundle tree must match the registry's pin
  → manifest validation (license, agentsec_min_version, name)
  → strict TI check (every threat_refs_required ID must already be in
    src/agentsec/audit/ioc/threat_intel.yaml)
  → loader test (every case file parses as a TestCase)
  → atomic rename into ~/.agentsec/suites/<name>/
```

Any failure leaves the local store untouched.

## Hash mismatches

If `agentsec suite install <name>` exits with code **2** and prints
`HASH MISMATCH`, the upstream tarball no longer matches the registry's
audited version. Possible reasons:

- The upstream tag was force-pushed to point at different content
- The upstream repository was tampered with
- A network-layer attacker is serving a different archive

Do **not** add `--force` and re-run. Instead, file an issue at
https://github.com/raoliaoyuan/AgentSec/issues with the suite name and
both hashes.

## Local store layout

```
~/.agentsec/
  suites/
    <name>/
      manifest.yaml
      cases/
      fixtures/
      README.md
      .install-receipt.json
```

To find an installed suite's path: `agentsec suite info <name>`.

## Updating

There is no `update` command. To upgrade:

```bash
agentsec suite uninstall <name>
agentsec suite install <name>
```

Or use `--force` to skip the uninstall step.

## Hidden flags

- `--registry-url <url>` on `install` / `list` — override the registry
  source. Used for development. Production deployments should rely on
  the wheel-bundled `community-suites.yaml`.
- `agentsec suite hash <local-bundle-path>` — print the canonical hash
  of a directory. Used by index contributors when preparing a PR.
