Security rules

Security Mode is an optional security(...) block in a backend contract. The compiler checks it and reports findings with stable AXSEC rule IDs. The same IDs appear in local checks, CI, signed releases, contract pull requests, contract pages, and trace context. A declaration is never presented as proof that arbitrary handler code is safe. For the declaration syntax, see Domain and security models; for every field, see the security schema.

Diagram source

flowchart LR
  DECL["security declarations in .acore"] --> AN["AXSEC analyzer"]
  EVID["Extractor evidence: Go, FastAPI"] --> AN
  AN --> CHECK["axiom security check"]
  AN --> MAN["Signed security manifest in .axiom"]
  MAN --> GATE["Build and release gate"]
  MAN --> SERVER["Axiom server admission"]
  MAN --> CLIENT["Client runtime trace attributes"]
  MAN --> DASH["Cloud Dashboard"]

Declarations and extractor evidence both feed the analyzer. axiom security check reports findings without writing an artifact. axiom build signs the result into the .axiom contract as an axiom-security-manifest/v1 manifest, which the build gate, the Axiom server, the client runtime, and the dashboard read.

Modes

Add --fail-on-warning to axiom security check to fail on warnings too, for example in a review-only CI job. Structural errors, such as a reference to an unknown policy, stop compilation in either mode.

Example

With no guard or policy for an endpoint, strict mode reports AXSEC-001:

project(id: "notes-api", version: "1.0.0")
variant default(include: ["*"])

model Note { id: String }

endpoint GetNote(method: GET, path: "/notes/{id}") {
  request { path("id", type: String) }
  response(type: Models.Note)
}

security(mode: "strict")

The directory also needs an AxiomDeps.toml containing type = "backend".

axiom security check axiom.acore

Security Mode strict · 1 error(s), 0 warning(s) · 0 of 1 endpoints covered (0 direct, 0 default-policy)
AXSEC-001 ERROR [GetNote] `GetNote` is externally reachable but has no explicit public declaration or authorization policy.
  → Declare `security.endpoints[endpoint]` as public or bind it to a user-defined policy.
Error: security check found 1 error(s) and 0 warning(s)

Declaring the endpoint public clears the finding:

security(mode: "strict", endpoints: { GetNote: EndpointGuard(public: true) })

axiom build on the first version fails with security strict mode rejected build: 1 blocking AXSEC finding(s). In audit mode the same finding is a warning and the build succeeds.

Finding statuses

Severity

Most findings are mode-dependent: a warning in audit, an error in strict. The exceptions:

An error in audit mode is still non-blocking unless you add --fail-on-warning or switch to strict.

Rule families

Rule catalog

Extractor evidence without an SDK

The Go and Python (FastAPI) extractors record advisory facts in the signed manifest: dynamic network targets, process execution, filesystem paths, uploads, rate-limit signals, sensitive logging, and wildcard CORS. Each fact has a file, line, confidence, and short description. Rate-limit signals are recorded as evidence only and do not create a finding.

A fact can create a finding. It never grants access, marks a route public, or weakens a policy. Existing services therefore need no SDK; you declare or override a boundary in axiom.acore when the source evidence is incomplete.

Enforcement

The client runtime context is diagnostic only. Where no trusted server boundary evaluates the signed policy against a principal and resource, the dashboard labels the policy evidence declared_unproven instead of inventing a runtime decision.