> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cantina.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Apex scan manual

> A practical guide to scoping scans, timing them well, and giving Apex enough context to return useful findings.

* **Read:** 12 min
* **Updated:** Apr 28, 2026
* **Audience:** Workspace owners

## § 01 How to think about Apex

Treat Apex like a fast auditing team. It works best on whole systems rather than tiny diffs, with context about architecture, permissions, invariants, and integrations.

> **Key idea**
> Apex works best as a standalone scan of a coherent system. Aim it at one deployable unit at a time, not at every PR.

## § 02 When to run a scan

* Run after a meaningful batch of merged changes - not on every PR.
* Re-scan before major launches, risky refactors, upgrade work, or new external integrations.
* Avoid back-to-back scans on near-identical code.
* The first scan on a system is usually the highest-yield pass.

## § 03 Audit vs normal scans

Two scan modes, picked by what you already know about the system and how much is riding on the result.

**Normal scan**

* After a meaningful batch of changes, when you already understand the system.
* Follow-up passes on stable scope.
* When the change matters enough to re-check, but isn't a launch-grade event.
* When repos, trust boundaries, threat model, and focus areas are already known.

**Audit scan**

* First scan of a system, protocol, or large codebase.
* Before launch, major release, or external security review handoff.
* After changes to auth, permissions, upgrade paths, signing, payments, settlement, or privileged flows.
* When risk lives in interactions and trust boundaries rather than one file.

> **Don't burn an Audit on**
> A small PR (unless it crosses a critical trust boundary), a repeat scan on near-identical code, a tiny isolated change, or work where fast iteration matters more than assurance.

## § 04 Threat model guidance

Apex does not infer priorities from code alone. A few sentences in plain language change the output significantly.

* Say directly if griefing or DoS is out of scope.
* Say directly if privileged role abuse, signer misuse, upgrade risk, or fee math matters.
* Specify if only critical and high-severity findings matter.

## § 05 Scope and inputs

* Use one scan for one coherent system whenever possible.
* Provide the best documentation you have: README, architecture notes, trust boundaries, permissions, external integrations.
* Split unrelated apps, services, contracts, and infrastructure into separate scans.
* Do not expand scope just because everything lives in one repository.

### Helpful inputs

* Repository selections that map to one deployable unit or review target.
* Current docs explaining architecture, permissions, upgrade paths, and integrations.
* Focused notes on assumptions, legacy paths, sharp edges, and sensitive flows.

## § 06 Splitting large repos

A large monorepo is rarely one review target. The split you want is the split a security reviewer would draw if they had to read the whole thing.

1. **Split by deployable system** - When services ship independently, scan them independently.
2. **Split by trust boundary** - Isolate areas that handle secrets, auth, payments, signing, or other privileged actions.
3. **Split by runtime** - Contracts, backend services, frontend apps, and infrastructure are materially different systems.
4. **Keep code together only when** - It should be reasoned about as a single security surface.

| Repository shape                              | Typical scan count | Why                                                                           |
| --------------------------------------------- | ------------------ | ----------------------------------------------------------------------------- |
| Focused repository                            | 1 scan             | One deployable unit, one review target.                                       |
| Small monorepo, a few distinct systems        | 2–3 scans          | One scan per coherent system; don't merge unrelated surfaces.                 |
| Large monorepo or mega-repo                   | 4+ scans           | One scan per major subsystem; separate by deployable or trust boundary first. |
| Two directories, unclear shared review target | Separate           | If you can't justify them as one review target, they aren't one.              |

## § 07 Planning template

Use this skeleton to decide how to split a repository or mega-repository into Apex scans. It is the template served at /docs/manual/[scan-planning-template.md](http://scan-planning-template.md).

[**apex-scan-planning-template.md**](http://apex-scan-planning-template.md)

```javascript theme={null}
# Apex Scan Planning Template
# Decide how to split a repository into Apex scans.

Repository:
  name:        <repo name>
  url:         <git url>
  type:        single-app | monorepo | mega-repo
  top_level:   [apps/, services/, contracts/, infra/]
  runtimes:    [ts, go, solidity]
  sensitive:   [auth, payments, signing, upgrade]
  existing_docs: <links to architecture, threat model, API specs>
  known_excludes: [vendor/, generated/, build/]

Goals:
  - Decide scan count for this repo
  - Explain why each scan is its own review target
  - Call out what NOT to group together
  - Identify missing docs / context to add first

# Rules of thumb
# - One scan per coherent security surface
# - Split contracts / backend / frontend / infra / admin tooling
# - Split by deployable or trust boundary first
# - Skip generated, vendor, build, dependency directories
# - Keep PR-review scans separate from broad baseline scans
Recommended split:                # example output
  - scan_1: contracts/ + shared protocol libs
  - scan_2: services/* (backend)
  - scan_3: infra/ + deployment logic
Do not combine: contracts with backend — different runtimes & trust models
Add before scanning: upgrade-path notes, signer permissions, fee math invariants
```