{
  "schema_version": 1,
  "skill_name": "secure-software-engineering",
  "evals": [
    {
      "id": "threat-model-feature",
      "prompt": "We are adding a file-upload endpoint to our web application that accepts images from unauthenticated users and serves them back. Before we build it, I want a threat model. What do I consider, and how should I structure the threat modeling session?",
      "expected_output": "A threat model for the upload feature organized around the system's assets, trust boundaries, and attackers: the response walks the data flow (upload, storage, validation, serving) and identifies the threats at each boundary — malicious file content (malware and polyglot files), denial of service (unbounded size, decompression bombs, resource exhaustion), stored cross-site scripting when files are served inline, path traversal and overwrite of existing files, content-type spoofing bypassing image validation, and abuse of the storage as a hosting vector. For each threat it proposes controls mapped to the threat: strict content validation by magic bytes plus re-encoding, size and count limits, serving from a separate origin or with Content-Disposition and no inline HTML, randomized storage keys never derived from user input, and rate limits. The response uses a structured method (e.g., STRIDE or a data-flow walk) and records decisions so the review is auditable.",
      "assertions": [
        "The threat model walks the data flow and identifies threats at each trust boundary",
        "Upload-specific threats are covered: malware, decompression bombs, stored XSS, path traversal, content-type spoofing",
        "Controls are mapped to each threat, including magic-byte validation, size limits, and randomized storage keys",
        "Serving mitigations such as separate origin or Content-Disposition are specified",
        "A structured method is used and decisions are recorded for auditability"
      ]
    },
    {
      "id": "security-requirements",
      "prompt": "We are designing a new customer-facing API that exposes account data, and security keeps being an afterthought. I want security requirements written into the design before implementation. What requirements should the design carry?",
      "expected_output": "A security-requirements set written as testable design constraints, not slogans: authentication requirements (which mechanism, token lifetime and refresh policy, where tokens are stored), authorization requirements (least privilege, per-resource access checks at the data layer rather than hidden in the UI), data-handling requirements (encryption in transit and at rest, what sensitive fields are collected at all and the minimization rule), input and output requirements (validation of untrusted input, no sensitive data in logs or error messages), and operational requirements (secret management, audit logging of access to sensitive data, key rotation). The response explains how each requirement is verified during implementation and review, and it prioritizes the requirements by the harm they prevent so the team knows what cannot be deferred.",
      "assertions": [
        "Requirements are written as testable constraints covering authentication, authorization, and data handling",
        "Authorization is specified as least-privilege with data-layer access checks",
        "Data minimization, encryption, and sensitive-data-in-logs rules are explicit",
        "Operational requirements cover secret management, audit logging, and key rotation",
        "Requirements are prioritized by the harm they prevent"
      ]
    },
    {
      "id": "authn-authz-review",
      "prompt": "In a code review I noticed our new endpoint checks 'is the user logged in?' but not 'is this user allowed to see this specific document?'. The frontend hides buttons based on role, and the API trusts that. What is the risk and what should the design enforce?",
      "expected_output": "A review finding that separates authentication from authorization: the response explains the risk precisely — hiding buttons in the frontend is not a security control, and an API that trusts UI state allows direct requests to access documents the caller should not see, which is an insecure-direct-object-reference or missing-object-level-authorization pattern. It prescribes the fix: every API handler must independently check authorization against the resource (the caller's identity and their relationship to the specific document) at the data-access boundary, not in the controller only, with deny-by-default behavior and tests that hit the endpoint directly without the UI to prove access is denied. It also covers the general principle: authorization checks belong where the data is read, and the frontend's role-based UI is a UX concern, not a control.",
      "assertions": [
        "The response identifies the missing object-level authorization as the core risk",
        "It explains why frontend button-hiding is not a security control and direct API access bypasses it",
        "The fix enforces per-resource authorization at the data-access boundary with deny-by-default",
        "Tests are prescribed that hit the endpoint without the UI to prove denial",
        "The response distinguishes authentication from authorization and UI-state from security control"
      ]
    },
    {
      "id": "untrusted-input-secrets",
      "prompt": "Our service parses user-supplied YAML files, runs some of the fields through a templating engine, and stores API keys in a config file committed to the repository. I know both are wrong but I need a concrete plan to fix them. What do I do?",
      "expected_output": "A hardening plan for both problems with the risks stated precisely: YAML parsing is unsafe for untrusted input (aliases and object construction can execute code), so the response prescribes parsing with a safe configuration (no arbitrary object instantiation) or moving to a stricter format with a schema, and treating the templating engine as code execution by design with input sandboxed and never fed raw user content. The second half addresses the committed API keys: rotate the exposed keys immediately, remove them from history-aware secrets management going forward (inject via environment or a secret store, never the repository), and scan the repository to confirm no other secrets remain. The response sequences the work by urgency: rotate exposed keys first, then fix parsing, then templating, with verification for each step.",
      "assertions": [
        "The YAML risk is stated precisely and fixed with safe parsing or a stricter schema",
        "The templating engine is treated as code execution and hardened against untrusted input",
        "Exposed API keys are rotated immediately and moved to environment or secret-store injection",
        "A repository scan confirms no other secrets remain",
        "The plan is sequenced by urgency with verification at each step"
      ]
    },
    {
      "id": "dependency-evaluation",
      "prompt": "A teammate wants to add a new npm package to our backend service. It is popular, but we have been burned before by abandoned dependencies and supply-chain surprises. What is a proper dependency evaluation before we accept it?",
      "expected_output": "A dependency evaluation covering the dimensions that matter for supply-chain safety: maintenance and community health (release cadence, response to issues, bus factor), the dependency's own dependency tree (transitive bloat and known vulnerabilities), provenance and integrity (published from a verified account, signatures, and the maintainer's reputation), license compatibility, the security-relevant surface (does it parse untrusted input, does it touch the network or filesystem), and the fallback cost if it is abandoned (how much code would need to be forked). The response produces a decision framework: acceptable with a pinned version and periodic review, acceptable only behind isolation, or rejected, and it prescribes the ongoing controls: lockfiles, automated vulnerability scanning in CI, and a review cadence for critical-path dependencies.",
      "assertions": [
        "The evaluation covers maintenance health, transitive dependencies, and known vulnerabilities",
        "Provenance, integrity, and license compatibility are checked",
        "The security-relevant surface of the package is assessed",
        "The decision framework includes rejection and isolation options, not just acceptance",
        "Ongoing controls are prescribed: lockfiles, CI scanning, and review cadence"
      ]
    },
    {
      "id": "multi-tenant-boundary",
      "prompt": "We run a pooled SaaS API with a separate control plane. Design the security review for tenant identity propagation, support impersonation, caches, search, queues, exports, backups, and deletion. Keep the SaaS placement decision and capacity modeling with their specialist owners.",
      "expected_output": "A security-focused review that treats control-plane to application-plane handoffs as trust boundaries; derives tenant context from verified identity; independently authorizes downstream services, workers, and support tools; defines scoped, expiring impersonation; covers cache, search, queue, export, backup, deletion, keys, logs, and restore boundaries; and names direct negative tests and provisioning/deprovisioning evidence. It explicitly routes end-to-end SaaS architecture and quantitative capacity evidence to their neighboring skills.",
      "assertions": [
        "Control-plane and application-plane trust boundaries, authority, freshness, and failure behavior are explicit",
        "Tenant identity is server-derived and re-authorized across APIs, workers, callbacks, and downstream services",
        "Privileged support and impersonation require scope, purpose, expiry, approval, and audit evidence",
        "Caches, search, queues, keys, logs, exports, backups, restore, and deletion are addressed as tenant-bearing boundaries",
        "The output routes SaaS architecture and capacity evidence to the named neighboring owners"
      ]
    },
    {
      "id": "tenant-resource-exhaustion",
      "prompt": "A large customer can saturate our shared queue workers and search cluster, causing smaller tenants to time out. Threat-model the issue and define security controls and proof without inventing universal utilization targets.",
      "expected_output": "A threat model for noisy-neighbor and resource-exhaustion abuse that identifies shared resource blast radius, tenant attribution, admission control, bounded work, per-tenant limits, fair scheduling or reserved capacity, backpressure, safe degradation, and abuse detection. It asks for tenant-distributed load or soak evidence and clearly routes sizing, utilization rationale, and cost tradeoffs to capacity-and-cost-engineering.",
      "assertions": [
        "The threat model identifies shared queue/search exhaustion and cross-tenant availability impact",
        "Controls include tenant attribution, bounded work, quotas or rate limits, fair scheduling or isolation, and safe degradation",
        "Verification requires tenant-distributed load or soak evidence and observes fairness and denial behavior",
        "The response avoids universal utilization targets and routes quantitative capacity decisions correctly",
        "The response distinguishes security controls from platform implementation details"
      ]
    },
    {
      "id": "tenant-lifecycle-privilege",
      "prompt": "Review a tenant offboarding flow where deletion is asynchronous and customer support can impersonate users to troubleshoot. What security requirements and evidence are missing?",
      "expected_output": "A review that requires authenticated, idempotent deprovisioning with revocation of sessions, tokens, jobs, callbacks, and export access; bounded handling of replicas, indexes, caches, logs, backups, and derived data; reconciliation and completion evidence; and support impersonation with named operator, purpose, target scope, approval, expiry, visible indication, least privilege, and audit trail. It routes privacy deletion artifacts to privacy-engineering rather than treating a security review as legal advice.",
      "assertions": [
        "Asynchronous deprovisioning includes authority, idempotency, revocation, blocking new work, retries, and reconciliation",
        "Deletion and retention evidence covers replicas, indexes, caches, logs, backups, exports, and derived data",
        "Support impersonation is scoped, time-limited, approved, visible, least-privileged, and auditable",
        "Direct negative tests cover stale jobs, revoked access, wrong tenant, and expired impersonation",
        "Privacy lifecycle ownership is routed to privacy-engineering"
      ]
    }
  ]
}

# AI And LLM Security

## Make The Decision Now

Define the AI system's boundaries before choosing prompts or models: who may invoke it, which data it may retrieve, which tools it may propose or invoke, what outputs can cause material effects, and where a human approval is required. The OWASP LLM release tag `2024`, titled `2025`, and MITRE ATLAS help elicit risks; neither is exhaustive.

## Treat The System As A Set Of Boundaries

- Treat user prompts, documents, retrieval results, model output, tool output, and external content as untrusted. Prompt instructions do not authorize access or execution.
- Enforce tool authorization server-side for every action with the requesting user, tenant, resource, purpose, and capability. Use narrow schemas, least privilege, rate and spend limits, and bounded data access.
- Require explicit human confirmation for material, irreversible, external, or high-impact actions unless a documented policy and risk acceptance justifies automation.
- Keep retrieval scoped to authorized data. Verify ingestion provenance, access labels, update behavior, and response citations where they affect decisions.
- Validate outputs before rendering, storing, sending, or executing them. Apply ordinary input/output controls to generated text, structured arguments, code, URLs, and files.
- Version and evaluate model, system policy, prompt templates, retrieval, tools, and guardrails. Log decisions and tool outcomes without retaining more prompt or customer data than needed.

## Evidence And Verification

Test prompt injection attempts, poisoned or irrelevant retrieval, cross-tenant retrieval, tool parameter manipulation, unauthorized tool calls, unsafe output contexts, approval bypass, rate exhaustion, and model or provider failure. Map relevant observed techniques to ATLAS when it improves communication, while recording the actual system-specific preconditions and mitigations.

## Misuse To Avoid

- Using a prompt as an access-control boundary.
- Giving a general-purpose agent broad credentials and trusting it to self-limit.
- Treating a model provider's safety claim, an evaluation score, or an LLM risk list as proof of safe deployment.

See [authentication-authorization.md](authentication-authorization.md), [input-validation-data-handling.md](input-validation-data-handling.md), [secure-logging-audit.md](secure-logging-audit.md), [dependency-supply-chain.md](dependency-supply-chain.md), [release-evidence.md](release-evidence.md), and [secure-code-review.md](secure-code-review.md) for the corresponding controls.

# Authentication And Authorization

## Make The Decision Now

Separate identity proof from permission to act. Select an authentication protocol only after defining the relying parties, token holders, browser or service trust, phishing resistance needs, session lifetime, and recovery path. OAuth or OpenID Connect can fit delegated access; they are not universal answers for service-to-service or local trust models.

## Design For Enforcement

- Define a server-side authorization decision for every protected action and object: subject, action, resource, tenant, and contextual constraints.
- Derive identity and tenant context from validated credentials or trusted server-side bindings. Never grant authority from a client request field, prompt, retrieved document, or tool output.
- Enforce object-level checks on reads, writes, exports, and indirect references. Apply least privilege to people, services, jobs, and AI tools.
- Make session issuance, renewal, revocation, logout, recovery, and privilege changes explicit. Bind tokens to intended audience and purpose where the protocol supports it.
- Give automation narrowly scoped, short-lived credentials and independently authorize each material tool action.

## Evidence And Verification

Keep an authorization matrix and tests that exercise allowed and denied cases across roles, objects, tenants, direct endpoints, bulk endpoints, jobs, and tool calls. Inspect middleware and downstream services to prove a gateway check is not bypassed. Test expired, revoked, wrong-audience, and confused-deputy credentials.

## Misuse To Avoid

- Authentication-only APIs that expose any object named by an identifier.
- Frontend-only role checks, broad administrator tokens, or authorization performed only at routing.
- Letting an LLM decide whether a tool action is authorized; use it to propose intent, then enforce policy server-side.

Use OWASP ASVS stable 5.0.0 and the OWASP API Security Top 10 2023 edition as control-selection and risk-awareness guidance where adopted. See [source-index.md](source-index.md) for exact sources.

# Dependency And Supply Chain

## Make The Decision Now

Decide whether a dependency, model, plugin, action, base image, or build tool is necessary; identify its maintainer, update path, permissions, licensing constraints, and compromise impact. Pin or constrain versions according to the ecosystem, then document how updates and vulnerabilities are evaluated.

## Evidence To Collect

- A reviewed dependency change, resolved lockfile or equivalent, source location, and documented license-obligation review by the authorized owner.
- Vulnerability assessment showing affectedness and disposition, not only scanner output.
- An SBOM in an agreed format such as CycloneDX 1.7 or SPDX 3.0.1, with component scope and generation time.
- Build provenance appropriate to the risk. SLSA v1.2 helps describe supply-chain integrity properties and evidence expectations.
- For AI systems, model, embedding, dataset, prompt-template, plugin, and tool-provider origin, version, access rights, and update path.

## What The Evidence Does Not Prove

An SBOM inventories declared components; it does not prove completeness, absence of vulnerabilities, secure configuration, or safe behavior. A provenance attestation supports a claim about a build's origin and process; it does not prove that source code, dependencies, or a model are benign. Verify signatures and predicates against the intended identity and policy rather than treating their presence as sufficient.

## Misuse To Avoid

- Floating version tags, unreviewed transitive upgrades, or dependency ownership assumptions.
- Giving CI, package installers, model plugins, or AI tools more permissions than their build task needs.
- Blocking a release on a raw vulnerability count without assessing reachability, exploitability, compensating controls, and an accountable exception.

Use SLSA v1.2, CycloneDX 1.7, and SPDX 3.0.1 from [source-index.md](source-index.md) as adopted standards or evidence formats, not universal requirements.

# Incident Learning

## Make The Decision Now

After an incident, near miss, or escaped defect, decide what systemic condition allowed it and which engineering artifact must change: requirement, threat model, design constraint, test, review prompt, telemetry, dependency policy, release gate, or operational response.

## Learn Without Replaying Harm

- Preserve minimum necessary facts, timelines, affected boundaries, decisions, and evidence access controls.
- Separate trigger, enabling conditions, detection gap, response effectiveness, and customer impact. Avoid assigning blame in place of identifying a controllable condition.
- Fix the class of defect across comparable paths, not only the observed instance.
- Convert learning into an owned change with acceptance criteria and a verification method. Update the threat model if an assumption failed.
- For AI incidents, include prompt sources, retrieval corpus, model and policy versions, tool authorization, approvals, output handling, and data exposure without retaining unnecessary sensitive content.

## Evidence And Verification

Show the changed control in code, configuration, test, review process, or release evidence. Test the original failure mode and adjacent variants; record residual risk when reproduction is unsafe or access is unavailable. Use [verification-methodology](../../verification-methodology/SKILL.md) for verdicts rather than declaring learning complete from a meeting note.

## Misuse To Avoid

- Calling a root cause a single human mistake and leaving the system condition unchanged.
- Collecting unrestricted incident data that creates a second exposure.
- Adding a permanent control without an owner, effectiveness check, or review date.

# Input Validation And Data Handling

## Make The Decision Now

For every input source, decide its schema, size, encoding, allowed operations, destination context, retention, and failure behavior. Inputs include HTTP parameters, files, headers, URLs, webhooks, queues, environment-derived configuration, imports, prompts, retrieved content, and tool responses.

## Build A Boundary Pipeline

- Parse with a format-specific parser, validate against an allowlist schema before business logic, and reject ambiguous or oversized input.
- Keep data as structured values. Use parameterized interfaces for queries, safe APIs for process execution, constrained file paths, and URL allowlists with network egress controls where relevant.
- Encode output for its actual consumer context. Validation does not make HTML, SQL, shell, templates, logs, or downstream prompts safe by itself.
- Classify and minimize stored data. Apply access controls, encryption choices, retention, deletion, and export rules to the classification and threat model.
- Treat prompts, retrieval results, model output, and tool output as untrusted data. Constrain tool arguments with schemas and validate model-produced values before execution or display.

## Evidence And Verification

Map every source to its validation and sink. Add negative tests for malformed input, injection-shaped values, traversal, unsafe redirects, SSRF targets, dangerous deserialization, content-type mismatch, and output-context encoding. Test that rejected data does not reach a privileged sink or leak through errors and logs.

## Misuse To Avoid

- Blacklists that miss encodings or syntax variants.
- Sanitizing once and reusing a value in a different output context.
- Treating a model or retrieval system as a trusted parser, policy engine, or authorization boundary.

Use OWASP ASVS stable 5.0.0, OWASP Top 10:2025, and relevant OWASP Cheat Sheets as adopted implementation guidance; verify exact controls before citing them.

# Multi-Tenant Isolation

Security owns the threat model and enforceable controls for tenant boundaries. The
end-to-end SaaS architecture, commercial tiers, placement strategy, and lifecycle
authority belong to [multi-tenant-saas-architecture](../../multi-tenant-saas-architecture/SKILL.md).

## Make The Decision Now

State the isolation promise per tenant tier and resource. For compute, storage,
keys, queues, caches, search, logs, backups, exports, support paths, and recovery,
record whether tenants share a pooled boundary, use a bridge boundary with a
dedicated sensitive component, or receive a silo boundary. A tier name is not a
control: identify the mechanism, the failure it prevents, and the evidence that
supports the promise. Route demand distributions, quota sizing, fairness targets,
and unit-cost evidence to
[capacity-and-cost-engineering](../../capacity-and-cost-engineering/SKILL.md).

## Model The Two Planes

Treat the control plane and application plane as distinct trust boundaries even if
they run in one deployment. The control plane may decide tenant identity,
placement, entitlements, support grants, provisioning, suspension, export, and
deletion; it must not become an unrestricted reader of application data by default.
The application plane serves tenant work and must consume authenticated,
versioned policy state without treating a client claim as authority.

For every crossing, document the actor and authority, credential audience, tenant
and user context, policy version, freshness rule, failure behavior, idempotency
key, and audit event. A stale or unavailable control-plane decision must fail in a
defined safe mode, not silently widen access. Provisioning and deprovisioning
commands need authenticated origin, replay protection, duplicate handling, and
reconciliation evidence. Platform implementation of network, workload, secret,
logging, and backup substrate belongs to
[platform-engineering](../../platform-engineering/SKILL.md).

## Propagate Identity Without Trusting Labels

Derive tenant context from a verified user or workload identity and an authoritative
membership/placement lookup. Bind it to the request, transaction, job, trace,
export, and downstream call using a server-controlled context. Reject missing,
stale, mismatched, or audience-confused context. A tenant ID in a header, URL,
queue payload, callback, cache key, or JWT custom claim is an input to validate,
not proof of authority.

At each hop preserve the subject, tenant, actor type, delegated purpose, resource
scope, and correlation identifier. Downstream services and workers must authorize
again within their own authority; gateway authentication or an upstream predicate
is not sufficient. API and event contract details belong to
[api-design-and-evolution](../../api-design-and-evolution/SKILL.md), while service
middleware, data access, jobs, and integration tests belong to
[backend-engineering](../../backend-engineering/SKILL.md).

## Protect Privileged Support Paths

Support access and impersonation are separate administrative capabilities, not a
special case that bypasses tenant authorization. Require a named operator, an
approved purpose, target tenant and resource scope, time limit, ticket or case
reference where policy requires it, and a visible session indicator. Prefer
read-only or customer-approved actions; require step-up approval for writes,
exports, key access, deletion, or cross-tenant investigation. Prevent chaining
impersonation into broader operator privileges, and make break-glass access
expire automatically.

Record who initiated, who was impersonated, why, what policy allowed it, which
objects were touched, what changed, and when the grant expired. Test direct API,
bulk, background, and support-tool paths with expired, revoked, wrong-tenant, and
cross-tenant grants. Audit-event design and sensitive-field minimization belong
to the logging owner; the security requirement is that the action be attributable
and reviewable.

## Apply Controls To Every Tenant-Bearing Resource

- **Data and keys:** Scope queries and object stores by server-derived tenant
  context. Use separate accounts, databases, schemas, namespaces, predicates,
  RLS, workload boundaries, or key hierarchies as the promise requires. Per-tenant
  keys can reduce blast radius but do not replace authorization; define key access,
  rotation, disablement, recovery, and destruction evidence.
- **Caches, search, and queues:** Include an authoritative tenant and resource
  scope in cache identity and invalidation. Filter search at query authorization
  and index/write boundaries. Bind queue messages, worker credentials, callbacks,
  retries, dead letters, and replay tools to tenant scope. Never let a shared
  worker select a tenant solely from message data.
- **Logs and traces:** Keep tenant context for investigation without copying
  customer payloads into shared telemetry. Separate audit access from ordinary
  operators, restrict query scope, redact secrets and sensitive content, and
  define retention and deletion behavior. A trace ID is correlation, not an
  authorization token.
- **Backups, restore, export, and deletion:** Define whether backup snapshots
  are pooled, bridge, or siloed and who may restore them. Restore into a bounded
  quarantine before serving data; verify tenant identity, key availability,
  authorization, and integrity. Exports must be tenant-scoped, purpose-bound,
  time-limited, encrypted, and independently authorized. Deletion must cover
  primaries, replicas, indexes, caches, queues, logs, derived data, exports, and
  backups according to the adopted retention policy, with completion and gap
  evidence. Route lifecycle and privacy acceptance artifacts to
  [privacy-engineering](../../privacy-engineering/SKILL.md).
- **Resource controls:** Give each tenant and tier explicit concurrency, storage,
  request, queue, search, export, and job limits where exhaustion can cross a
  boundary. Protect shared pools with admission control, bounded work, fair
  scheduling, backpressure, and reserved capacity where justified. A quota is
  not a capacity model; route sizing, load/soak evidence, hot-tenant analysis,
  and cost tradeoffs to [capacity-and-cost-engineering](../../capacity-and-cost-engineering/SKILL.md).

## Threat Cases

Threat-model at least these abuse paths and add design-specific variants:

| Case | Security question | Evidence to seek |
|---|---|---|
| Control-plane compromise or confused deputy | Can a provisioning, support, entitlement, or restore capability read or alter application data beyond its purpose? | Separate credentials and policy tests for each plane and privileged command. |
| Context substitution | Can a caller replace tenant context between authentication, lookup, queueing, storage, or downstream calls? | Direct, asynchronous, retry, and callback tests with mismatched context. |
| Support impersonation abuse | Can an operator hide, prolong, chain, or broaden an impersonation session? | Approval, expiry, scope, audit, revocation, and break-glass tests. |
| Shared-resource bleed | Can cache reuse, search ranking, logs, backups, exports, or dead letters reveal another tenant? | Distinct sentinel data and negative tests at every resource boundary. |
| Noisy neighbor or exhaustion | Can one tenant consume shared workers, connections, memory, queue depth, search capacity, storage, or export bandwidth and deny another? | Tenant-distributed load/soak evidence, quotas, fairness observations, and safe degradation. |
| Lifecycle race | Can a suspended, deleted, or deprovisioned tenant continue receiving jobs, tokens, exports, or restored data? | Provision/deprovision state machine tests, tombstone handling, retries, and reconciliation records. |

## Evidence And Verification

Build an authorization matrix and a resource-boundary inventory. Prove, with
distinct tenants and tiers, allowed and denied reads/writes, direct and bulk API
paths, worker retries and replays, cache hits, search results, logs, keys, backup
restore, exports, deletion, support impersonation, and resource exhaustion. Verify
that a new tenant is born with restrictive permissions, scoped credentials,
tenant-aware observability, limits, and no unintended shared data.

For deprovisioning, show the initiating authority, state transition, revocation
of sessions and jobs, blocking of new work, completion across every store, and
reconciliation of failures. Record evidence location, test environment, policy
version, owner, and residual gap. A passing database test does not prove that
cache, search, logs, backups, queues, support tools, or capacity boundaries are
safe.

## Misuse To Avoid

- Treating a pooled, bridge, or silo label as proof without naming its actual
  isolation mechanism and failure blast radius.
- Filtering tenant IDs only in the UI or trusting client headers, URL segments,
  queue fields, trace fields, or support claims.
- Treating control-plane administrator access, database privilege, or restore
  access as permission to view every tenant's application data.
- Calling a database boundary complete while cache keys, logs, search indexes,
  asynchronous workers, exports, backups, or deletion jobs remain shared.
- Calling a rate limit or quota capacity evidence without representative load,
  distribution, fairness, and degradation measurements.
- Granting an AI agent tenant-wide capability when the user needs a
  document-scoped capability; prompts and retrieval content cannot grant access.

# Release Evidence

## Make The Decision Now

Decide what release claims matter, who owns them, and which artifacts can support or refute each claim. Typical claims concern the source revision, build identity, dependency inventory, test results, approval, deployment configuration, rollback readiness, and known-risk exceptions.

## Build An Evidence Bundle

- Link the release to an immutable source revision and reproducible build inputs where feasible.
- Generate and retain an SBOM in the consumer-agreed CycloneDX 1.7 or SPDX 3.0.1 format.
- Retain provenance attestation and signature verification results when the supply-chain policy calls for them; validate issuer and predicate against policy.
- Record security tests, threat-model changes, review approvals, deployment checks, accountable exceptions, expiry or review dates, rollback path, and incident-response contact.
- Include AI model, retrieval corpus, prompt or policy version, tool configuration, evaluation results, and human-approval gates where they affect release behavior.

## What It Proves And Does Not Prove

An SBOM supports an inventory claim at its generation scope and time. Provenance supports a claim about an identified build process. Test results support only the behavior exercised in the stated environment. None proves absence of vulnerabilities, secure deployment configuration, or safe AI behavior. CISA Secure by Design joint guidance encourages transparency and manufacturer accountability; publish or share artifacts according to the product's data-handling and disclosure policy.

## Exceptions And Verification

An exception needs a named owner, rationale, affected scope, compensating controls, expiry or review date, and rollback or response path. Independently retrieve and validate artifacts, verify deployment identity against the approved revision, and rehearse a rollback or containment action appropriate to release risk.

# Secrets Lifecycle

## Make The Decision Now

For each credential, key, token, certificate, or signing material, decide its owner, purpose, scope, acquisition method, storage boundary, delivery path, revocation path, and event- or risk-driven rotation conditions. Do not add a secret merely to avoid designing identity or authorization.

## Design The Lifecycle

- Prefer workload or user identity with short-lived, scoped credentials over distributed static material when the environment supports it.
- Store secrets in an access-controlled secret system or platform mechanism; inject them only where needed and avoid source control, images, build logs, command lines, crash reports, and client bundles.
- Separate environments and duties. Limit who can read, change, deploy, or audit each secret.
- Define detection and response for exposure: revoke or disable, replace dependent material, identify affected use, and preserve minimum necessary evidence.
- Rotate when compromise, staff or vendor changes, cryptographic policy, expiry, or risk warrants it. Routine rotation without safe rollout, rollback, and dependency inventory can create outages without reducing material risk.

## Evidence And Verification

Maintain a non-secret inventory with owner, scope, expiry, and rotation trigger. Test least-privilege retrieval, redaction, revocation, and replacement in a non-production path. Review repository history and generated artifacts for accidental exposure without printing sensitive values.

## Misuse To Avoid

- Hardcoding credentials in examples, configuration defaults, tests, or AI prompts.
- Logging authorization headers, raw tokens, request bodies, or model context that can contain secrets.
- Calling an encrypted value "managed" while broad identities can still retrieve it.

# Secure Code Review

## Make The Decision Now

Review the change against its trust boundaries and acceptance criteria, not a generic list alone. Identify what authority, data flow, dependency, deployment capability, or AI tool behavior the change adds or alters; request a threat-model update when the answer is unclear.

## Review Method

1. Read the intended behavior, security criteria, architecture change, and tests.
2. Trace untrusted inputs to privileged sinks, including queries, shell or process calls, URLs, files, templates, logs, queues, model prompts, retrieval, and tools.
3. Trace identity and tenant context from verification through every object, background path, and downstream service.
4. Inspect error, retry, timeout, exceptional, and rollback paths; OWASP Top 10:2025 includes mishandling exceptional conditions as a risk category.
5. Review dependency, configuration, CI, infrastructure, and release-artifact changes alongside code.
6. State each finding as evidence, impact, exploit precondition, remediation, and verification. Separate observed facts from assumptions.

## Evidence And Verification

Require tests for denied authorization, malformed input, cross-tenant access, secret redaction, dependency integrity decisions, and relevant AI action approvals. Use a second reviewer or focused security review for material boundary changes. A passing review checklist is evidence that questions were asked, not proof that no vulnerability remains.

## Misuse To Avoid

- Reviewing only changed lines when a new endpoint or dependency changes a system-wide boundary.
- Accepting tests that prove an allowed path but never exercise denial, revocation, or failure.
- Treating model output as reviewed code or allowing it to introduce uninspected dependencies and privileged operations.

Use [templates/secure-code-review-checklist.md](../templates/secure-code-review-checklist.md) to structure review prompts.

# Secure Logging And Audit

## Make The Decision Now

Choose which security-relevant events need accountability, detection, or investigation, then define their minimal fields, access controls, retention, integrity expectations, and response owner. Log a decision and its evidence, not every sensitive input.

## Design For Useful Evidence

- Capture identity or workload, action, target, authorization result, time, request or correlation identifier, and policy or configuration version when they are needed to reconstruct a material event.
- Redact or avoid credentials, raw tokens, sensitive payloads, personal data, prompts, retrieved documents, and model context unless a documented investigation need outweighs exposure risk.
- Protect log transport, storage, query access, and deletion. Separate operational logs from high-value audit events when their access and retention needs differ.
- Preserve ordering and integrity signals appropriate to the threat model; alerting and immutable storage are design choices, not automatic guarantees.
- Log server-side tool authorization, execution outcome, user approval, and data destination for AI actions. Do not log private model context by default.

## Evidence And Verification

Review event schemas and run representative actions, denied attempts, privilege changes, tenant-bound operations, secret exposure responses, and AI tool requests. Verify that authorized investigators can answer the intended question without seeing prohibited data. CISA Secure by Design joint guidance supports transparency and ownership; it does not require indiscriminate collection.

## Misuse To Avoid

- Calling application debug output an audit trail.
- Making logs so complete that they become an unprotected copy of customer or secret data.
- Recording a successful request without the authorization decision, resource, or actor needed to investigate it.

# Security Requirements And Threat Modeling

## Make The Decision Now

Decide what harm the feature must prevent, which assets and actions matter, and where the system changes trust. Create a short model before implementation and revise it when flows or assumptions change. Use the per-component STRIDE questions in [security-audit-methodology](../../security-audit-methodology/references/threat-modeling.md) when they reveal useful threats; do not force every category onto every component.

## Work From Evidence

1. Inventory assets, including credentials, tenant data, money-moving actions, audit records, model inputs, retrieved documents, and tool capabilities.
2. Name actors and their current versus required authority. Include services, administrators, background jobs, support staff, external providers, and AI agents.
3. Draw data flows and mark crossings such as browser-to-service, service-to-store, tenant-to-shared worker, model-to-tool, and build-to-release.
4. Write assumptions that can be disproved: identity issuer validation, tenant context propagation, queue visibility, retrieval corpus curation, or build isolation.
5. Turn plausible abuse into mitigations and measurable acceptance criteria. Record likelihood, impact, owner, and residual risk.

Evidence is the reviewed model, data-flow diagram, design decision, and tests or configuration proving each mitigation. The model is incomplete if it omits failure paths, administrative paths, data export, asynchronous work, or AI tool calls.

## Hypothetical Abuse Cases

Use scenarios like these as prompts, then replace them with cases grounded in the actual design:

| Boundary | Hypothetical abuse | Design question | Verification idea |
|---|---|---|---|
| User to object API | An authenticated user requests an object owned by another user or tenant. | Where is object-level authorization enforced? | Exercise allowed and denied object/tenant combinations through direct and bulk paths. |
| External sender to webhook | An attacker forges or replays a message. | How are origin, integrity, freshness, and idempotency established for this protocol? | Submit forged, modified, duplicate, and stale messages. |
| API to background worker | A job carries a client-supplied tenant identifier into shared processing. | How does the worker derive and independently enforce tenant context? | Attempt cross-tenant job, cache, search, and storage access. |
| Retrieved document to AI tool | Retrieved text instructs the model to disclose data or invoke a privileged tool. | Why can untrusted content not grant authority or expand retrieval scope? | Inject conflicting instructions and verify server-side policy still denies the action. |
| Model to external side effect | Model output proposes a material or irreversible action without valid approval. | Which capability, validation, authorization, and human gate apply? | Manipulate tool arguments and approval state; confirm no side effect occurs. |

## Misuse To Avoid

- Treating a diagram as a threat model while leaving assets, assumptions, and mitigations unstated.
- Trusting client-supplied roles, tenant identifiers, prompt instructions, or callback claims.
- Limiting the model to request/response paths and missing caches, jobs, backups, telemetry, search, and release automation.

## Verify

For each material boundary, show where authentication, authorization, input handling, failure behavior, logging, and resource limits are enforced. Confirm an abuse case fails safely in a test or review the explicit reason it cannot be tested. Use OWASP ASVS 5.0.0 control objectives and OWASP Top 10:2025 only as adopted context, not as proof of coverage.

# Source Index

Use this manifest to select a source for a concrete decision, not to imply that every source is binding. A source becomes a requirement only when an organization, contract, regulator, or applicable policy adopts it. Versions and URLs were checked on 2026-07-13.

| Source | Exact version or release | Canonical URL | Source type and adoption context | Decision use |
|---|---|---|---|---|
| NIST Secure Software Development Framework | SP 800-218 v1.1, 2022-02 | https://doi.org/10.6028/NIST.SP.800-218 | U.S. guidance; adopt where policy or risk management calls for it | Organize security work and evidence across the lifecycle. |
| NIST SSDF AI Profile | SP 800-218A Final, 2024-07 | https://doi.org/10.6028/NIST.SP.800-218A | U.S. guidance for AI development practices | Adapt lifecycle controls for AI components and suppliers. |
| OWASP ASVS | stable 5.0.0, tag `v5.0.0_release`, 2025-05-30 | https://github.com/OWASP/ASVS/releases/tag/v5.0.0_release | Application security verification standard and control catalog | Select and test application control objectives. |
| OWASP Top 10 | 2025 | https://owasp.org/Top10/2025/ | Awareness and risk-categorization guidance | Communicate web application risk without substituting for a threat model. |
| OWASP API Security Top 10 | 2023 edition, verified 2026-07-13 | https://owasp.org/API-Security/editions/2023/en/0x11-t10/ | API risk-awareness guidance | Review object and function authorization, resource consumption, inventory, and third-party API use, including tenant context at API and event boundaries. |
| OWASP Cheat Sheet Series | retrieved 2026-07-13 | https://cheatsheetseries.owasp.org/ | Implementation guidance | Compare framework-specific patterns after choosing a control objective. |
| CISA Secure by Design | joint guidance, 2024 update | https://www.cisa.gov/securebydesign | Joint manufacturer guidance | Prefer secure defaults, ownership, and transparent evidence. |
| SLSA | v1.2 | https://slsa.dev/spec/v1.2/ | Supply-chain framework | Decide what build provenance claim to seek and verify. |
| CycloneDX | 1.7 | https://cyclonedx.org/specification/overview/ | SBOM and supply-chain standard | Choose an SBOM exchange format suited to consumers. |
| SPDX | 3.0.1 | https://spdx.github.io/spdx-spec/v3.0.1/ | SBOM, license, and software metadata standard | Choose interoperable component and license evidence. |
| MITRE ATLAS | retrieved 2026-07-13 | https://atlas.mitre.org/ | AI adversary behavior taxonomy | Describe AI threat techniques; it is not exhaustive. |
| OWASP Top 10 for Large Language Model Applications | release tag `2024`, titled `2025` | https://github.com/OWASP/www-project-top-10-for-large-language-model-applications/releases/tag/2024 | LLM risk awareness guidance | Elicit prompt, tool, data, and model boundary risks. |
| NIST Cybersecurity Framework | CSF 2.0, 2024-02 | https://doi.org/10.6028/NIST.CSWP.29 | Voluntary cybersecurity risk-management framework | Frame tenant-boundary ownership, protection, detection, response, and recovery evidence without treating the framework as a control checklist. |
| NIST SP 800-57 Part 1 Rev. 5 | 2020-05 | https://csrc.nist.gov/pubs/sp/800/57/pt1/r5/final | Key-management guidance | Inform key ownership, separation, lifecycle, recovery, and destruction questions for tenant-scoped data. |

When citing a control, state the decision, selected source, version, evidence, and what would falsify the claim. Do not rely on unchecked section numbers; verify them against the exact release before using them.

For the multi-tenant reference, public sources are decision aids rather than a
copied checklist. The procedure is an original synthesis organized around trust
boundaries, resource-specific promises, abuse cases, and verification. SaaS
architecture choices remain with `multi-tenant-saas-architecture`; quantitative
capacity evidence remains with `capacity-and-cost-engineering`; privacy lifecycle
artifacts remain with `privacy-engineering`; and substrate implementation remains
with `platform-engineering`.

# Lightweight Threat Model

> **Confidentiality:** A completed threat model can expose system boundaries and weaknesses. Store it with access controls appropriate to sensitive project security information.

## When To Use

Use before implementing a new feature, integration, service, sensitive data flow, tenant boundary, or AI capability. Adapt the prompts to the risk; this is a thinking tool, not a compliance form.

## When Not To Use

Do not use this as evidence that an existing system has been assessed. Use `security-audit-methodology` for authorized assessment work.

## System Overview

What does the system or change do? What data and actions flow through it?

## Assets

| Asset | Sensitivity or harm if compromised | Location or flow | Owner |
|---|---|---|---|
| <asset> | <harm> | <where> | <owner> |

## Actors And Authority

| Actor or workload | Trust basis | Current authority | Required authority | Explicitly denied |
|---|---|---|---|---|
| <actor> | <credential or boundary> | <current> | <needed> | <denied> |

## Data Flows And Trust Boundaries

Describe each flow and where trust changes. Include clients, services, stores, workers, external providers, build systems, and AI model/retrieval/tool paths when applicable.

For a diagram, ask the `c4-diagramming` skill to render the components and labeled boundaries from this description.

## Assumptions To Test

| Assumption | Why it matters | Evidence or test | Owner | Status |
|---|---|---|---|---|
| <assumption> | <impact> | <evidence> | <owner> | <open/verified> |

## Component Threats

Use applicable STRIDE prompts from `security-audit-methodology/references/threat-modeling.md` or another suitable method.

| Component or boundary | Abuse or failure case | Preconditions | Mitigation | Verification | Residual risk |
|---|---|---|---|---|---|
| <component> | <case> | <conditions> | <control> | <test/evidence> | <risk> |

## AI Boundaries (If Applicable)

| Boundary | Untrusted content | Allowed capability | Server-side enforcement | Approval gate |
|---|---|---|---|---|
| <prompt/retrieval/tool> | <content> | <scope> | <policy> | <when> |

## Decisions And Follow-Up

| Risk or decision | Likelihood | Impact | Chosen mitigation | Owner | Delivery phase | Exception or review date |
|---|---|---|---|---|---|---|
| <item> | <low/medium/high> | <low/medium/high> | <action> | <owner> | <phase> | <date or none> |

# Secure Code Review Checklist

## When To Use

Use for a change that creates or alters a trust boundary, authority, data flow, dependency, release path, tenant behavior, or AI capability. Record evidence and findings, not just checked boxes.

## When Not To Use

Do not use this checklist as a substitute for a threat model, authorization test, or authorized security assessment. Escalate unclear boundaries rather than marking them passed.

## Change Context

- Change and intended behavior: <description>
- Threat-model or acceptance-criteria link: <link>
- Reviewer and evidence location: <reviewer/link>

## Boundary Review

- [ ] Every input reaches a defined parser, schema, limit, and safe sink.
- [ ] Query, process, path, URL, serialization, template, log, and output contexts are reviewed where present.
- [ ] Errors, retries, timeouts, exceptional conditions, and rollback do not leak data or bypass policy.

## Identity, Authority, And Tenancy

- [ ] Authentication is validated for the actual trust model.
- [ ] Server-side authorization checks every action and object, including jobs and bulk paths.
- [ ] Tenant context is derived and enforced in storage, cache, queues, search, logs, and resource controls.

## Secrets, Dependencies, And Release

- [ ] No credentials or sensitive values enter source, artifacts, logs, errors, or AI context.
- [ ] New dependencies, models, plugins, actions, and build inputs have a reviewed origin, version, permissions, and update plan.
- [ ] Release evidence and exception handling state what is supported and what remains unproven.

## AI Boundaries (If Applicable)

- [ ] Prompts, retrieval, model output, and tool output are untrusted.
- [ ] Tool actions are authorized server-side, narrowly scoped, and validated before execution.
- [ ] High-impact or irreversible actions have an appropriate approval gate.

## Findings And Verdict

| Finding or assumption | Evidence | Impact | Required action | Owner | Verification |
|---|---|---|---|---|---|
| <item> | <evidence> | <impact> | <action> | <owner> | <proof> |

# Security Acceptance Criteria

> **Confidentiality:** Completed criteria can describe security boundaries. Keep them within the project's appropriate access controls.

## When To Use

Use while writing a feature specification, design decision, or pull request description. Replace prompts with observable, feature-specific criteria and direct evidence.

## When Not To Use

Do not treat unchecked items or headings as semantic validation. Use `verification-methodology` to assess evidence and record a verdict.

## Scope And Threat Model Link

- Feature or change: <description>
- Assets and trust boundaries affected: <link or summary>
- Security owner and review date: <owner/date>

## Authentication And Authorization

- [ ] Identity is verified at <boundary> using <trust basis>; evidence: <test/configuration>.
- [ ] Server-side authorization permits <actor> to perform <action> on <resource> only under <conditions>; denied cases tested: <cases>.
- [ ] Object and tenant checks cover direct, bulk, asynchronous, and tool-mediated paths: <evidence>.

## Input, Output, And Data

- [ ] Inputs from <sources> have schemas, limits, and rejection behavior: <evidence>.
- [ ] Outputs for <contexts> are encoded or constrained appropriately: <evidence>.
- [ ] Data classification, retention, export, and deletion decision: <decision/evidence>.

## Secrets And Dependencies

- [ ] New or changed secret material has owner, scope, storage, revocation, and event/risk-driven rotation plan: <evidence or not applicable>.
- [ ] Dependencies, models, plugins, and build inputs have version, origin, affectedness, and update decision: <evidence>.

## Logging And Release

- [ ] Security-relevant events logged: <events>; excluded or redacted data: <data>; access and retention: <decision>.
- [ ] Release evidence includes <SBOM/provenance/tests/approvals>; limitations and exceptions: <limits/owner>.
- [ ] Rollback and response path: <path/owner>.

## AI-Specific Boundaries (If Applicable)

- [ ] Prompts, retrieved content, and tool output are treated as untrusted: <evidence>.
- [ ] Every tool action is authorized server-side and constrained to <capability/data scope>: <evidence>.
- [ ] Material or irreversible actions require <approval/policy>: <evidence>.