How the fork works
Build a read-only graph, fork it, model a change, and inspect consequences before deployment.
The harness between AI and cloud
An agent should not need direct access to a live account. Emfirge sits between the agent and cloud as a safe workspace: the agent proposes, Emfirge branches and measures the change, and your own pipeline decides what to apply.
The workflow
A scan builds a connected graph from a read-only role. Fork a completed analysis with emfirge_create_branch, add an operation with emfirge_apply_change, then inspect emfirge_branch_diff and emfirge_branch_verdict.
emfirge_create_branch({ base_analysis_id: "<analysis_id>", name: "restrict-public-access" })
emfirge_apply_change({ branch_id: "<branch_id>", op: "modify", resource_type: "rds_instance", resource_id: "<database_id>", fields: { publicly_accessible: false } })
emfirge_branch_verdict({ branch_id: "<branch_id>" })
Honest limits
Branches are models, not deployments. Emfirge does not apply branch changes to AWS, and a result from any one lens does not prove application connectivity or every operational consequence. Re-scan when the live environment changes.
The graph
A scan reads the cloud through a read-only role and builds a connected infrastructure graph. The graph is the saved base for subsequent analysis; it is not a live write target and becomes stale as the account changes.
Complete workflow
The flow is: read-only scan → fork graph → apply modeled branch change → diff the branch → re-run analysis lenses → advisory verdict.
Use emfirge_create_branch to fork a completed analysis, add an emfirge_apply_change operation to the isolated model, then inspect emfirge_branch_diff and emfirge_branch_verdict. The verdict is native-rules-only by default; Checkov, Trivy, and cloudsplaining are disabled unless EMFIRGE_RUN_SCANNERS=1. When enabled, available scanner lenses are included and reports coverage explicitly.
emfirge_create_branch({ base_analysis_id: "<analysis_id>", name: "restrict-public-access" })
emfirge_apply_change({ branch_id: "<branch_id>", op: "modify", resource_type: "rds_instance", resource_id: "<database_id>", fields: { publicly_accessible: false } })
emfirge_branch_diff({ branch_id: "<branch_id>" })
emfirge_branch_verdict({ branch_id: "<branch_id>" })
The six branch-verdict lenses
A branch verdict compares the modeled base and proposed branch across documented lenses. Blast radius is an attack-path/critical-resource metric surfaced by emfirge_attack_paths, not a distinct branch-verdict lens; verdict does not compute deletion blast-radius. Each lens answers a concrete AWS question, exposes its exact verdict fields, and states what the model cannot establish.
| AWS question | CombinedVerdict mapping | Honest bound | Worked example |
|---|---|---|---|
| Security — Which native findings are new or removed? | CombinedVerdict.native_added / CombinedVerdict.native_removed | 51 verified check functions across supported rule families cover defined families, not every possible issue. | Opening SSH to 0.0.0.0/0 adds an internet-reachable EC2 finding. |
| Reachability — What becomes or stops being reachable from the internet? | CombinedVerdict.newly_internet_reachable / CombinedVerdict.no_longer_internet_reachable | Modeled graph reachability, not a live connectivity probe. | Attaching a public subnet path makes a modeled service newly internet-reachable. |
| Blast radius — What paths are reachable from a compromised node? | No standalone blast-radius or attack-path CombinedVerdict field; related finding and attack-path payloads expose it, while the verdict summarizes resulting finding deltas. | Only modeled graph edges, known resources, and known paths. | A compromised modeled role reaching a data store appears in its attack-path payload. |
| IAM privilege escalation — Does the change introduce an IAM escalation path? | CombinedVerdict.introduces_privilege_escalation. Policy/action metadata from Policy Sentry informs upstream analysis; its annotations are not CombinedVerdict fields. | IAM policy/action coverage and modeled principals, not proof of exploitability. | Adding a modeled pass-role path marks privilege escalation as introduced. |
| Cost — What is the provisioned monthly cost delta? | CombinedVerdict.cost_delta_monthly_usd / CombinedVerdict.cost_unknown_notes | Usage-based costs remain unknown and labeled; Emfirge never fabricates them. | Adding a provisioned resource produces a monthly delta while usage-based charges remain unknown. |
| Limits / capacity — Which limits does the change approach or breach? | CombinedVerdict.limits_introduced / CombinedVerdict.limits_resolved | Deterministic checks, not forecasting or a live quota guarantee. | Adding resources beyond a modeled service limit adds a capacity finding. |
Borrowed scanners and coverage
In the hosted service Checkov runs on each branch verdict through a separate, memory-capped worker, only on changed resources and their neighbours, with base results cached; cloudsplaining runs in process when installed; Trivy is off. Self-hosted engines run scanners only when EMFIRGE_RUN_SCANNERS=1. Scanners run at arm's length against the branch; they do not become native rules. Their findings are advisory: they warn and never block on their own unless the check is crosswalked to a published severity (the crosswalk is empty today). Their findings fold into scanner_added and scanner_removed alongside the same combined verdict.
Missing executable or package, unreachable worker, timeout, invalid or empty output, disabled scanner, or another unavailable state degrades honestly: scanner_status reports each state and coverage_warnings says the result is NOT full coverage. Do not assume all scanners always run.
Combined verdict
block, warn, or pass combines native and scanner deltas, reachability, cost, privilege escalation, limits, and the human-readable summary into one advisory result. It proves the change against a model, not the live cloud: it computes a security delta and never guarantees safety.
coverage_warnings is non-empty when lenses are missing or disabled. A degraded result must not be described as complete coverage or a guarantee of safety. A pass means no modeled concern was found by available analysis, not that deployment is risk-free.