---
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:

```bash
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` |