security-context-spec

Imported from TGPSKI/security-context-spec (AGENTS.md). Install upstream with npx skills add TGPSKI/security-context-spec. Copyright stays with the author.

Security Context Spec

Structured, portable, machine-readable security context for code repositories. SARIF (2020, OASIS) standardized scanner output; this spec standardizes scanner input — the security-relevant context that every scanner rediscovers on every run.

This is a specification repository, not a deployed service. Changes here affect the spec document, JSON Schema, reference validator, scanner, and examples.

Design Principle (The Gate)

Every field must either change a security finding or eliminate a security-relevant discovery step.

This is the acceptance filter for every proposed addition. A field that models mechanism without security effect (e.g., "which secret manager" or "which CI system") doesn't pass. Five sections were cut from v1.0 for failing this filter — they're preserved in decisions/proposals/broad-spectrum-expansion.md for potential promotion if scanner feedback justifies them.

Repository Layout

Three Artifacts That Must Stay Aligned

Any schema change requires updating all three — they are independent implementations of the same spec:

The spec is authoritative. The JSON Schema and Go validator are derived from it. When they disagree, the spec wins.

Working Principles

1. Read the spec before changing validation. The spec defines what's valid. Don't add an enum value to main.go without first adding it to the spec.
2. Never invent enum values. All enums are closed sets defined in spec section 3. Adding a value is a schema change and requires the proposal process.
3. One Go dependency. Both tools/validate and skills/generate-security-context/scripts depend only on gopkg.in/yaml.v3. Don't add dependencies.
4. Examples are contracts. All 8 examples must pass make validate. Use acme/ org names in examples, never real organizations.
5. Unknown top-level keys are intentional. The validator silently ignores unknown top-level keys for forward compatibility (spec §4). Unknown fields within defined sections are validation errors — enforced via raw map key checking against knownSectionKeys.

Development Workflow

make check            # Full CI locally: lint + fmt-check + test + validate. Always run before finishing.
make validate         # Build validator, then validate all examples/*.yaml
make test             # Go tests for both validator and scanner
make lint             # go vet (both packages) + JSON Schema syntax + symlink integrity
make fmt / fmt-check  # gofmt for both packages

Other useful targets:

make build            # Build validator binary only
make build-scan       # Build scanner binary
make scan REPO=/path  # Scan a repo for detectable security properties
make validate-file FILE=path/to/file.yaml  # Validate a single file

Schema Change Process

Schema changes go through the proposal lifecycle — don't edit the spec, schema, or validator directly for structural changes:

make proposal NAME=my-change       # Create from decisions/TEMPLATE.md
# Fill in: Context, Schema Changes, Scanner Value, Alternatives, Impact
# Open PR for discussion
make accept PROPOSAL=my-change     # Move to decisions/accepted/
make reject PROPOSAL=my-change     # Move to decisions/rejected/

After acceptance, implement across all three artifacts + examples + CHANGELOG.

Spec Sections (v1.0)

Validator Internals

Relevant when editing tools/validate/main.go:

• Enum sets: map[string]bool built by set() helper. One set per enum (e.g., statusEnum, exposureEnum).
• checkEnum(path, value, allowed): Validates against set; skips empty values (optional fields).
• checkDate(path, value): Parses YYYY-MM-DD via time.Parse("2006-01-02", ...).
• CVE pattern: ^CVE-\d{4}-\d{4,}$ — regex validated on known_unreachable entries.
• CWE pattern: ^CWE-\d+$ — regex validated on suppress and accepted_risks entries.
• Per-section validators: validateMetadata, validateSecurityProperties, validatePrerequisite, validateRelationship, validateDependencies, validateAcceptedRisk, validateScanningDirectives.
• Output format: OK: {file} is valid or FAIL: {file} — N error(s): with {section}.{field}: {message} lines.

Scanner Capabilities

The scanner at skills/generate-security-context/scripts/scan.go detects security properties from files on disk:

Trust Model

The .security-context.yaml file is a declaration of context, not a grant of authority. The team whose code is scanned maintains it. Scanners decide how much weight to give each field. Scanners SHOULD NOT silently suppress findings — always report what was suppressed. Security teams MAY audit the file. Expired accepted_risks SHOULD be flagged.

CI Requirements

Two-tier structure:

• ci job (tier 1) — runs on every push and PR. Single job with all lint/test/build/validate steps. This is the sole required status check for merge.
• full-scope job (tier 2) — cross-platform matrix (linux/arm64, macos/arm64). Only runs on full-test label, workflow_dispatch, or push to main. Informational — doesn't block merge.

Actions are SHA-pinned with version comments. Runner is pinned to ubuntu-24.04. Go version read from go.mod via go-version-file. Concurrency group cancels superseded PR runs.

Common Tasks

Example Files Reference

Use these as starting points when generating .security-context.yaml files in consumer repos:

Contributing

One logical change per PR. Update CHANGELOG.md under [Unreleased]. make check must pass. No new Go dependencies. Schema changes require the proposal process — don't skip it.

License

Apache-2.0