generate-security-context

name	generate-security-context
description	Generate or update a .security-context.yaml file for any repository. Runs a deterministic Go scan to detect security properties from repo files, interviews the practitioner for context scanners can't infer, and produces a validated file. Use when someone wants to create a security context file, add scanner context, or update an existing .security-context.yaml.
license	Apache-2.0
compatibility	Requires Go toolchain (1.22+) for scan script and validator.
metadata	{"author":"TGPSKI","version":"1.0"}

Generate Security Context

Produce a valid .security-context.yaml for the current repository. The file declares security-relevant context that scanners consume to adjust severity, suppress false positives, route ownership, and assess blast radius.

Design Principles

• Ownership: The team that owns the code maintains the file. The agent assists with generation — it does not decide what to declare.
• Source of truth: The repository itself. Derive security properties from Dockerfiles, K8s manifests, NetworkPolicies, and package files before asking the user.
• Ask less, infer more: Every question must earn its keep. If the answer is in a file on disk, read the file. Only ask for decisions that can't be observed.
• Prefer simple: Start with metadata and security properties. Offer prerequisites, relationships, and accepted risks only when the user is ready for that depth.
• Trust model: .security-context.yaml is a declaration of context, not a grant of authority. Scanners decide how much weight to give each field.

Prerequisites

• Start from an up-to-date primary branch. Sync your fork and rebase onto the latest upstream main before invoking this workflow. Progress detection relies on the contents of .security-context.yaml on the primary branch.
• Start with a clean chat session. Prior conversation history causes the agent to conflate previous output with actual repository state.

Entry Point

Inspect: Run the scan script to get structured detection results:

go run skills/generate-security-context/scripts/scan.go /path/to/target/repo

If the scan binary is pre-built, use it directly. The scan outputs YAML with detected values and source annotations for every field.

Ask:

1. "Is this the repo you want to generate a security context file for?" (confirm repo name from scan output)

Detect Current Progress

After confirming the repo, inspect .security-context.yaml (if it exists) to determine what's already been completed.

Progress Detection

Check	What to Look For	Indicates
No file	.security-context.yaml missing	New repo — Phase 1
Metadata only	metadata present, no security_properties	Phase 1 partial
Foundation complete	metadata + security_properties present	Phase 1 complete
Threat model present	prerequisites or relationships present	Phase 2 complete
Finding modifiers present	accepted_risks or scanning_directives or dependencies.known_unreachable present	Phase 3 complete
All sections populated	All 7 sections present	Fully configured — run drift detection

Determine Phase

Detected State	Recommended Action
No .security-context.yaml	Start at Phase 1
Metadata exists, no security_properties	Continue Phase 1
Foundation complete, no threat model	Continue at Phase 2
Threat model complete, no finding modifiers	Continue at Phase 3
All sections populated	Drift detection — check for expired risks, changed manifests, new base images

Drift Detection (fully configured repos)

When all sections are populated, run these checks before asking the user what to update:

Check	How	Finding
Expired accepted risks	accepted_risks[].expires < today	List expired entries, recommend re-review or removal
Base image drift	Compare dependencies.base_images[].image to current FROM lines in Dockerfiles	Show mismatches
Security property drift	Compare security_properties to current K8s manifests, Dockerfiles	Flag runs_as_root, privileged, read_only_root mismatches
New deployment resources	Look for NetworkPolicy, Ingress, Route files added since last_reviewed	May change network_isolated or exposure
Scanner ignore file changes	Check if .trivyignore, .snyk, .semgrepignore were added or modified	Candidates for portable scanning_directives migration

Present the delta, then ask which sections to update.

Route to Phase

Ask: "Based on my analysis, you appear to be at [detected phase]. Would you like to:

1. Continue from [detected phase]
2. Start from a different phase
3. Review what's already configured"

User Choice	Action
Continue detected phase	Load the corresponding phase file
Different phase	Ask which phase, then load that file
Review configuration	Show current .security-context.yaml, then ask which phase

Phase Files

Phase	File	Description	Sections Covered
1	references/phase-01-foundation.md	Repo scan, metadata, security properties	metadata, security_properties
2	references/phase-02-threat-model.md	Prerequisites and cross-repo relationships	prerequisites, relationships
3	references/phase-03-finding-modifiers.md	Dependencies, accepted risks, scanning directives	dependencies, accepted_risks, scanning_directives