Get Controls
get_controlsRetrieve implementation controls for a threat model: list controls with filters, pagination, and status, or fetch one control's full detail including evidence and verification status.
Instructions
Get implementation controls for a threat model — list or single-control detail. Read-only (with one list-mode side effect, below).
Two modes, selected by whether control_id is set:
List mode (
control_idomitted) — returns the controls that should be implemented to satisfy the model's control objectives, as{"controls": [...], "total": N, "returned": M}. One side effect: if controls have never been generated for this model, the first call triggers generation. Generation may finish inline or continue in the background — if results look incomplete, pollget_control_generation_statusand re-read once it reportscomplete. The filters (status,co_id,component_id), pagination (offset/limit), and theinclude_deleted/include_orphaned/summary_onlytoggles apply only in this mode. By default list mode excludes ORPHANED controls (controls whose every mapped CO is tombstoned because its asset/attacker pair was removed in a later version); passinclude_orphaned=Trueto include them — each returned control carries a booleanorphanedfield so callers can render the distinction.Detail mode (
control_idset) — returns a single control directly (NOT wrapped in an array) with verified-status enrichment and anorphanedflag derived from the live CO set. 404 if the control doesn't exist on the requested version. Passversionto read the control as of a specific model version. The list-mode filters, pagination, and toggles are ignored in this mode.
Objective mapping is not coverage credit. The control-objective ids a
control carries record which objectives it is ATTACHED to, not which ones
it is required to satisfy. Within an objective, a control is either a
member of a required mitigation group or it is defense-in-depth, which is
tracked but earns no mitigation credit. A control that is defense-in-depth
on every objective it touches can be fully implemented and fully verified
without moving a single objective out of at-risk. Read
get_mitigation_groups for the per-objective role before deciding a
control is worth evidence work — the id list alone will not tell you
whether proving it changes anything.
Two different status fields — do not conflate them. status is the
operator-set implementation state (not_implemented / implemented
/ verified). verification_status and is_verified are the
EVIDENCE state, derived from the control's assertions:
"verified"— every assertion passes both tiers AND they collectively cover the whole control description."partially_verified"— deliberately covers three distinct situations, so it does not by itself tell you what to fix: some assertion FAILED a tier, or all passed but leave clauses of the description UNPROVEN, or the control leaned on an operator attestation that has since EXPIRED. Callget_sufficiencyon the control to find out which."pending"— assertions exist, some still awaiting evaluation."unverified"— no assertions submitted at all.
A control with assertion_count well above zero and every tier
passing can still read partially_verified; that is the normal state
for evidence narrower than the description promises, and the fix is
more assertions (or a narrower description), never a verdict recompute.
A for-all clause — one that ranges over every entry of a surface — is
credited only by a sound type bound to it with covers; an
attestation never substitutes. What each clause still needs is served
per clause by get_control_work_order in required_evidence.
Filtering status="implemented" returns controls the operator marked
implemented that have NOT been promoted to verified — the right filter
for "what still needs evidence work". It reads this model's OWN stored
controls; controls inherited through composition are counted by
assess_model but are managed on their source model.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| co_id | No | List-mode filter — control objective ID. | |
| limit | No | List mode — max controls to return (0 = all). | |
| offset | No | List mode — skip the first N controls (pagination). | |
| status | No | List-mode filter — "implemented", "not_implemented", or "verified". | |
| version | No | Detail mode only — model version to read the control from. 0 (default) uses the latest. Ignored in list mode. | |
| model_id | Yes | ID of the threat model. | |
| control_id | No | If set, detail mode — return this one control's full record directly (e.g. ``CTL-12``). If omitted, list mode. | |
| component_id | No | List-mode filter — component ID (e.g., "CMP1"). | |
| summary_only | No | List mode — if True, returns only id, description, status, assertion_count, and assumed_by per control (much smaller response). | |
| server_version | Yes | ||
| include_deleted | No | List mode — include soft-deleted controls (default False). | |
| include_orphaned | No | List mode — include controls mapped only to tombstoned COs (default False). |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||