How it works
wyrm init # auto-detect compose in the current dir wyrm init --from k8s/ # a directory of Kubernetes manifests wyrm init --from main.tf -o - # print to stdout wyrm init --from tfplan.json # a Terraform plan (fully expands modules) wyrm init --from ./chart # a Helm chart (rendered via `helm template`) wyrm init --from ./overlay # a Kustomize overlay (rendered via kustomize) wyrm init --from gitops/ # ArgoCD/Flux β follows each app to its local source wyrm analyze # then find the threats in the baseline
π’ GitOps: wyrm follows ArgoCD / Flux to the workloads they deploy
An ArgoCD Application or a Flux Kustomization/HelmRelease
is a pointer, not a workload. wyrm reads the pointer's source.path (Argo),
path (Flux Kustomization) or chart path (HelmRelease), resolves it against the scan
root, renders that local Helm chart / Kustomize overlay / manifests, and folds the workloads into
the model β so the app the pipeline actually ships is what gets analysed. A source in a
remote git repo can't be followed offline: wyrm emits a note telling you to clone it
locally and re-run, rather than silently dropping it.
Kubernetes-native controls become mitigations that downgrade findings, the
same way a WAF or IAP does: a default-deny NetworkPolicy, an Istio
AuthorizationPolicy, and STRICT mutual-TLS (PeerAuthentication) each
attach to the workloads they govern; an egress NetworkPolicy/FQDNNetworkPolicy
is recorded too. So a locked-down mesh no longer scores like a wide-open one.
π Environments: slice the model by prod / staging / β¦
wyrm stamps an environment attribute on each component so a model spanning many
envs can be filtered and risk-weighted per env β statically, with no plan. Three signals, in order:
- Path (default) β a directory whose next segment names the env
(
environments/prod/β¦βprod). Markers default toenvironments/envs/env. - Scope map β for repos where the env is a variable, not a folder,
assert
dir-prefix β envyourself (longest prefix wins). - Literal label β a resource
labels/tagsvalue (interpolatedvar.environmentvalues are skipped, not guessed).
Tune it in .threatmodel/environments.yaml:
pathMarkers: [environments, envs, env] # dir segment before the env name scopes: # for var-based layouts uapi: prod infra/core: shared
Where one root module deploys to many envs via a var.environment, no static signal
can name a single env β those components stay unclassified rather than mislabelled.
π§© Multiple sources: one model for the whole system
Pass --from more than once to combine repos into a single model β the Terraform
that provisions the clusters and the GitOps repo that deploys onto them, together:
wyrm init --from infra-terraform/ --from gitops-manifests/ -o system.otm.yaml
Each component is tagged with its source (terraform/kubernetes),
and Kubernetes workloads are re-homed into the cluster trust zone of their
environment β so an app lands in the cluster it actually runs on. Clusters and workloads
match by env name; reconcile spellings or pin the mapping explicitly in
.threatmodel/environments.yaml:
aliases: { production: prod } # TF says production, ArgoCD says prod
clusterMapping: { prod: tz-cluster-main } # or pin it outright
Per-env cluster linking is exact when the Terraform side has concrete clusters (a
terraform show -json plan); from raw HCL where clusters live behind module calls,
workloads fall back to the single cluster zone if there's one.
π§© Terraform modules: point wyrm at a plan for full resolution
Reading .tf directly, wyrm sees resources inside local modules but can't
expand count/for_each or reach registry/git modules β the same blind
spot every HCL scanner has. For a complete, collision-free picture, feed it the plan Terraform
already resolved:
terraform plan -out=tfplan terraform show -json tfplan > tfplan.json wyrm init --from tfplan.json
Every resource then arrives with its module-scoped address
(module.data.google_sql_database_instance.main) β modules unnested, instances
expanded, nothing lost to name collisions. Same detection rules, exact topology.
Reading raw .tf without a plan still works for multi-module and multi-env
layouts: wyrm walks every .tf file and, when the same resource name appears in two
different module directories, path-qualifies the colliding ids
(envs-prod-aws_db_instance-main vs envs-dev-β¦) so neither is clobbered.
Names unique to one directory keep their clean id.
It writes .threatmodel/<project>.otm.yaml. Two principles guide
every rule:
- Defaults favor exposure. If a load balancer's
internalflag is absent, it's treated as internet-facing β because that's the provider default. wyrm errs toward flagging exposure, not hiding it. - A WAF is a mitigation, not a wall. Detecting Cloudflare, Cloud Armor,
or a Next-Gen WAF attaches a control to the ingress flow and downgrades the
finding β it never makes it disappear. Detect-only rules (
action = "log") don't count.
What it detects
Status: shipped building planned
Docker Compose shipped
| Signal | Becomes |
|---|---|
| service | component (type inferred from image) |
published ports | internet ingress dataflow |
depends_on | dataflow between services |
| image is postgres/mysql/redis/β¦ | database / data-store in a data tier |
Kubernetes & Istio shipped
| Signal | Becomes |
|---|---|
Service type LoadBalancer / NodePort | internet-facing component |
Service type ClusterIP | internal component |
Ingress (+ backends) | edge entrypoint + dataflows; tls β encrypted |
Istio Gateway / VirtualService | mesh edge + routing dataflows |
loadBalancerSourceRanges | mitigation (source-IP allowlist) |
NetworkPolicy, Istio AuthorizationPolicy / mTLS | trust boundary / mitigation |
| CNI: Flannel vs Calico/Cilium | whether NetworkPolicy is actually enforced |
Terraform β AWS / GCP / Azure shipped
| Signal | Becomes |
|---|---|
AWS aws_lb.internal = false, API Gateway | internet-facing LB / API |
AWS aws_security_group ingress 0.0.0.0/0 | world-open port |
GCP forwarding_rule EXTERNAL*, public GKE | internet exposure |
GCP iap {}, master_authorized_networks | mitigation (auth / allowlist) |
GCP Cloud Armor attached to a backend (security_policy), *_security_policy | WAF mitigation linked to the HTTPS ingress β downgrades edge exposure |
Azure public frontend_ip_configuration, azurerm_public_ip | internet-facing frontend |
google_compute_network / aws_vpc / azurerm_virtual_network | trust zone (VPC) |
google_compute_subnetwork / aws_subnet / azurerm_subnet | trust zone (subnet segment) |
| GKE / EKS / AKS cluster | edge control-plane node + a private "Cluster (internal)" zone for its workloads |
| a dir with both Terraform and Kubernetes manifests | one combined model β k8s workloads land in the TF cluster's zone |
WAF, DDoS, reverse proxies & access control planned
| Signal | Becomes |
|---|---|
| Cloudflare managed/custom WAF, rate limiting, bot management | mitigation (mode: block vs log) |
| Fastly WAF / Next-Gen WAF (Signal Sciences) | mitigation (+ coverage %) |
| AWS WAFv2 & Shield, GCP Cloud Armor, Azure WAF & DDoS | mitigation on the ingress flow |
Pangolin, Cloudflare Tunnel (cloudflared), ngrok | tunneled edge β no direct internet port + auth mitigation |
Authelia, Authentik, oauth2-proxy, Keycloak, Pomerium; Traefik forwardAuth | mitigation (authentication / SSO) |
Istio oauth2 ext-authz / JWT RequestAuthentication | mitigation (auth at the gateway) |
fail2ban, CrowdSec; IP allowlists (Traefik ipAllowList, nginx allow/deny) | mitigation (intrusion prevention / source allowlist) |
| Tailscale tailnet / subnet router | private trust zone (not internet-exposed) |
tailscale funnel | deliberate internet exposure |
The full signalβOTM mapping, with exact resource/attribute names, lives in DETECTION.md. Want a source wyrm doesn't cover yet? Issue #12 tracks the roadmap.
Annotate what it can't detect
A generated baseline captures structure. It can't know sensitivity (which data is PII), how access is provisioned, or which services talk to each other internally. You supply that context through annotations β two channels, one schema (full spec in ANNOTATIONS.md):
- External
.threatmodel/data.yaml, keyed by resource address β context without touching your infra code. Auto-loaded bywyrm init. - Inline comments next to a resource (Trivy-style), e.g.
# wyrm: assets=pii provisioning=jitβ context that lives with the code.
Precedence is inline > external > generated, and your direct edits to the
.otm.yaml still win on merge β so it all composes and survives regeneration.
# .threatmodel/data.yaml
assets:
- { id: pii, name: Customer PII, risk: { confidentiality: 100 } }
resources:
google_container_cluster.workloads:
assets: [pii]
flows: [google_sql_database_instance.main] # β declare an internal dataflow
google_project_iam_member.cluster_admin:
type: identity
provisioning: manual # manual | approval | attribute-based | jit
privilege: high
π‘ The sleeper feature: flows
Terraform and the like describe resources, not the traffic between them β so a
generated cloud model often has components but few edges, and STRIDE rules need edges to fire.
The flows key lets you declare the internal dataflows the code
can't express: flows: [db, cache] on a service says "it talks to these." Suddenly
analyze has a graph to reason over β a sensitive flow crossing a trust boundary
becomes a finding that simply wasn't visible before. It's the smallest annotation with the
biggest jump in signal: a handful of flows: lines turns an inventory into a real
data-flow diagram.