# Fairway Security Rule Selection Evidence v1

Status: governance rule
Fairway source task: `SEC-CODEGUARD-FAIRWAY-RULE-EVIDENCE-001`

## Purpose

Define the `security-rule-selection` evidence expected for high-risk Fairway
tasks that touch security-sensitive code, configuration, runtime behavior, or
operations.

This evidence records which external security rule families were considered,
why they apply or do not apply, and which review domains must inspect the work.
It is review input. It does not approve the task, waive findings, satisfy
release gates by itself, or override GPUaaS contract, tenant-isolation,
privacy, policy, audit, or production-readiness requirements.

## Upstream Guidance Pin

The initial external guidance source is Project CodeGuard as recorded in
`doc/operations/CodeGuard_Gap_Map_v1.md`:

```text
repository: https://github.com/cosai-oasis/project-codeguard
branch: main
commit: a557e7ea6b7a2897178fd97cd60792eebc0a957c
observed_at: 2026-06-10
```

Do not enable a remote CodeGuard MCP server, provider adapter, or new central
rule source until `SEC-CODEGUARD-MCP-TOOLING-REVIEW-001` approves that tooling
boundary. Until then, selection evidence is a pinned guidance reference and
manual review artifact.

## When Required

Record `security-rule-selection` evidence before review for any high-risk or
critical task that touches one or more of these areas:

| Area | Typical triggers |
|---|---|
| Authn/session | login, OIDC/JWT/JWKS, MFA, session renewal, service accounts, browser session handling |
| Authz/tenant boundary | RBAC, project/org/department scoping, ownership checks, IDOR-sensitive routes, admin APIs |
| Secrets/PKI | credentials, tokens, private keys, certificates, Vault, Step CA, Keycloak client secrets, transcript or evidence redaction |
| Runtime execution | node-agent, terminal, app runtime, command execution, image launch, task signing, mTLS, cleanup/isolation |
| Kubernetes/edge/IaC | Kubernetes manifests, ingress, NetworkPolicy, Pomerium, Cloudflare, cert-manager, runners, registry config |
| Supply chain/dependencies | generated artifacts, dependency changes, SBOM/provenance/signature gates, container image trust, CI/CD pipelines |
| Data protection/logging | PII, audit logs, sanitizer changes, telemetry, billing/ledger evidence, storage access, export paths |
| MCP/tooling/automation | MCP servers, provider adapters, browser/Chrome automation, local LLM use, provider-event adapters, Fairway automation utilities |

Medium-risk tasks should record this evidence when a declared review domain is
`security`, when the reviewer requests it, or when the task owner cannot rule
out one of the trigger areas. Low-risk tasks may use it as optional planning
evidence.

## Evidence Shape

Use `artifact-type=security-rule-selection` in Fairway. The attached artifact
may be a markdown or YAML file. The notes or artifact must include:

```yaml
kind: security-rule-selection
task_id: <fairway-task-id>
guidance_source:
  name: project-codeguard
  repository: https://github.com/cosai-oasis/project-codeguard
  commit: a557e7ea6b7a2897178fd97cd60792eebc0a957c
affected_source_paths:
  - <path-or-glob>
selected_rule_families:
  - name: <rule-family>
    applies_to:
      - <path-or-surface>
    applicability_rationale: <why this rule family applies>
non_applicable_rule_families:
  - name: <rule-family>
    non_applicability_rationale: <why it is not relevant to this task>
required_review_domains:
  - security
  - <architecture|ops|backend|frontend|governance>
reviewer_domain: <domain that prepared or accepted the selection>
residual_risk: <remaining risk after the selected rules and local controls>
follow_up_tasks:
  - <task-id or none>
```

The artifact should be compact. It should point to detailed evidence, tests,
scan results, or review packets instead of copying sensitive data. Never include
tenant names, customer names, credentials, tokens, private URLs with embedded
auth, private keys, raw session material, or incident-sensitive detail in the
selection metadata.

## Rule Families

Use these initial family names until a rule-pack loader or review-packet utility
provides a stricter vocabulary:

| Family | Use when work touches |
|---|---|
| `hardcoded-credentials` | credentials, tokens, test fixtures, config examples, CI secrets, transcript/evidence redaction |
| `crypto-certificates` | TLS, mTLS, certificate lifecycle, key custody, signing, CA integration |
| `authentication-session-management` | OIDC/JWT/JWKS, login, MFA, sessions, refresh, service account tokens |
| `authorization-access-control` | RBAC, ownership checks, tenant/project/org/department boundaries, admin routes |
| `api-web-services` | REST/WebSocket contracts, HTTP handlers, generated clients, error envelopes |
| `input-validation-injection` | request validation, SQL, shell commands, path handling, serialization/parsing |
| `client-side-web-security` | route guards, browser token handling, CSRF/XSS-sensitive UI or client API use |
| `cloud-kubernetes-cicd-containers-iac` | Kubernetes, Cloudflare, Pomerium, cert-manager, CI/CD, runners, containers, IaC |
| `supply-chain-security` | dependencies, generated artifacts, SBOM, provenance, signatures, image trust |
| `data-storage-privacy-logging` | PII, audit, sanitizer, logging/tracing, storage, exports, billing/ledger evidence |
| `mcp-tooling-security` | MCP, provider adapters, browser automation, local LLMs, transcripts, provider-event adapters |
| `xml-serialization-file-handling` | XML, structured file parsing, archive extraction, upload/download, filesystem paths |

If a family is broadly relevant but not actionable for the task, include it in
`non_applicable_rule_families` with the boundary rationale. Do not omit a
security-sensitive family only because the task owner believes existing GPUaaS
controls are stronger; record the stronger local control in the applicability
or non-applicability rationale.

## Required Tags And Review Routing

Use stable task tags so humans and future rule-pack tooling can route review
without inferring from prose alone:

| Trigger area | Suggested tags | Required review domains |
|---|---|---|
| Authn/session | `surface:authn`, `surface:session`, `surface:iam` | `security`, `backend`, `architecture`; add `frontend` for browser/session UX |
| Authz/tenant boundary | `surface:authz`, `surface:tenant-boundary`, `surface:admin-api` | `security`, `architecture`, `backend`; add `governance` for policy/process changes |
| Secrets/PKI | `surface:secrets`, `surface:pki`, `surface:credentials` | `security`, `ops`, `architecture`; add `backend` when service code changes |
| Runtime execution | `surface:runtime`, `surface:node-agent`, `surface:terminal`, `surface:app-runtime` | `security`, `backend`, `ops`, `architecture` |
| Kubernetes/edge/IaC | `surface:kubernetes`, `surface:edge`, `surface:iac`, `surface:runner` | `ops`, `security`, `architecture`; add `backend` for controller/service coupling |
| Supply chain/dependencies | `surface:supply-chain`, `surface:dependencies`, `surface:ci-cd`, `surface:registry` | `security`, `ops`, `governance`; add `backend` or `frontend` for package/runtime owners |
| Data protection/logging | `surface:data-protection`, `surface:logging`, `surface:audit`, `surface:storage` | `security`, `governance`, `backend`; add `ops` for observability/export paths |
| MCP/tooling/automation | `surface:mcp`, `surface:local-automation`, `surface:agent-security` | `security`, `ops`, `architecture`, `governance` |

When a task spans multiple areas, union the review domains and record any
deliberate omissions in the evidence. For high-risk work, the normal Fairway
high-risk review rule still applies: at least two independent domains are
needed, and launch-sensitive work may require architecture, security, and ops
even when the selection artifact is present.

## Fairway Command Pattern

Example:

```bash
fairway record evidence <task-id> \
  --artifact-type security-rule-selection \
  --artifact .fairway/artifacts/<task-id>/security-rule-selection.yaml \
  --result pass \
  --command-text "prepared security-rule-selection evidence for <task-id>" \
  --notes "Selected authn/session and authorization-access-control families; security and architecture review required."
```

Use `result=partial` when the affected paths or rule applicability are still
uncertain. A partial selection can support planning, but it should not be used
as final review evidence for high-risk work.

Use `result=fail` when the selection exposes a blocker, missing review domain,
missing owner, or required follow-up that must be resolved before review.

## Governance Boundary

`security-rule-selection` evidence is not:

- a security approval;
- a vulnerability waiver;
- a release authorization;
- a replacement for SAST/SCA/secret/container/DAST scans;
- a replacement for supply-chain evidence;
- a substitute for contract-first API/codegen gates;
- permission to enable remote MCP tooling or provider adapters.

Reviewers may approve, request changes, or require follow-up tasks based on the
selection. If the selected rule family exposes a deterministic missing control,
create or update a scoped Fairway task with the normal `detected_by` and
`expected_gate` classifiers from
`doc/operations/DevSecOps_Escape_Rate_Classifier_v1.md`.