Apex scan manual | Cantina AI

01How to think about Apex

Treat Apex like a fast auditing team with several review modes. Full scans work best on whole systems, PR scans work best on proposed diffs, and Fix Review works best when the question is whether a known finding has actually been fixed.

Key idea

Use the smallest workflow that answers the security question: full scan for a system, PR scan for a diff, Fix Review for an existing finding.

02When to run a scan

Run a full Standard or Audit scan after a meaningful batch of merged changes or when the system boundary changes.
Run a PR scan before merge when the pull request or merge request changes auth, permissions, payments, signing, upgrades, external integrations, or other sensitive behavior.
Run Fix Review after a proposed fix is pushed and ready for Apex to verify against the original finding.
Re-scan before major launches, risky refactors, upgrade work, or new external integrations.
Avoid back-to-back full scans on near-identical code when a PR scan or Fix Review would answer the narrower question.
The first scan on a system is usually the highest-yield pass.

03Scan type quick guide

Pick the scan type from the review target, not from habit. The same workspace can need different workflows at different moments.

Standard or Lite	Use for ordinary workspace coverage when the target is a coherent repository, service, or subsystem.
Audit	Use for launch-grade or high-risk system review when broader context and deeper coverage matter.
PR Scan	Use for focused review of one or more GitHub pull requests or GitLab merge requests before merge.
Fix Review	Use after a finding has a proposed fix and Apex should verify whether the original issue was resolved.

04PR scans

PR scans are focused security reviews for code that is still in a pull request or merge request. They are designed for diff review, not for replacing periodic whole-system scans.

Start from the workspace Run scan dialog and choose PR Scan, or invoke the configured Apex bot command from GitHub where PR scan comments are enabled.
Select the pull requests or merge requests to review. Apex scopes the run to changed files first, then follows nearby code only as needed to understand trust boundaries and exploitability.
Use PR scans for security-sensitive changes before merge, especially changes touching auth, permissions, money movement, signing, configuration, upgrade paths, or external calls.
If a diff is very large, incomplete, or crosses multiple systems, run a full Standard or Audit scan instead of treating the PR scan as complete coverage.
GitHub-invoked PR scans report progress and final results back through PR comments and checks; Apex also keeps the scan and findings visible in the workspace.

Escalate large diffs

When the PR or MR is broad enough that the changed files no longer describe the security surface, use a full scan. Apex may still run a focused PR scan, but the result should be treated as diff coverage.

05Fix Review scans

Fix Review is a verification pass for known findings. It asks whether the proposed change closes the original issue and whether the fix introduces an obvious adjacent problem in the reviewed target.

Start from an individual finding, a filtered finding set, or Run scan > Fix Review when the workspace has eligible findings.
Use linked GitHub pull requests or GitLab merge requests when the fix is in review; use current-repository review when the fix is already on a branch without a PR or MR.
Apex checks the proposed fix against the original finding, fix instructions, evidence, and changed code instead of running a general new audit.
Fix Review can run in batches across the current filtered finding set or all eligible workspace findings, and scheduled Fix Review can recheck older eligible findings on the workspace cadence.
For linked PRs or merge requests, Apex can publish result comments and checks so the fix outcome is visible next to the code review.

What Fix Review is not

Fix Review is not a replacement for a fresh scan of unrelated changes. Use a PR scan for a new diff, and use a Standard or Audit scan when the system changed beyond the original finding.

Read the full workflow

The Fix Review workflow guide covers single-finding review, agent handoff, bulk workspace review, scheduled rechecks, and result handling end to end.

06Audit 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 PR scan target, a Fix Review target, a repeat scan on near-identical code, a tiny isolated change, or work where fast iteration matters more than assurance.

07Threat 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.
For PR scans, add a short focus hint when the risky part of the diff is not obvious from the changed files.

08Scope 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.
For PR scans and Fix Review, keep the selected pull requests, merge requests, branches, and commits aligned with the actual review target.

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.
Fix PR or merge request links, or the branch Apex should inspect for current-repository Fix Review.

09Splitting 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.

Split by deployable system
When services ship independently, scan them independently.
Split by trust boundary
Isolate areas that handle secrets, auth, payments, signing, or other privileged actions.
Split by runtime
Contracts, backend services, frontend apps, and infrastructure are materially different systems.
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.

10Planning 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.

apex-scan-planning-template.md

# 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