Management
The threatware manage
actions (see manage) cause threatware to store/retrieve threat model approval status, metadata, and model data in a storage location.
The only currently supported storage location is git.
Setup
To enable this functionality an empty git repo needs to be created and the git remote URL populated in manage/manage_config.yaml
configuration file under the manage-config/storage/gitrepo/remote
key.
Either the user running threatware in a CLI environment, or the git credentials given the threatware running in AWS lambda, need permissions to create branches and push changes to this repo.
Content
By default, threatware will create the following dir structure in the git repo (over time, as threatware manage
actions are invoked on threat models) using a default branch called approved
(this is configurable):
├── threatmodels.yaml
├── CMP.TM.1
├── metadata.yaml
├── 1.0.yaml
├── 1.0.plain.yaml
├── 1.1.yaml
├── 1.1.plain.yaml
├── CMP.TM.2
├── metadata.yaml
├── 1.0.yaml
├── 1.0.plain.yaml
├── CMP.TM.3
├── metadata.yaml
├── 1.0.yaml
├── 1.0.plain.yaml
└── ...
Where
threatmodels.yaml
is the source of truth for the approval status and approval metadata for all threat models. The name of the file is configurable.Directories
CMP.TM.1
etc. contain the version history (inmetadata.yaml
) and approved models of each version of a threat model (1.0.yaml
contains the 1.0 version of the threat model model-data with all metadata included,1.0.plain.yaml
just contains the model-data and is meant to be more human readable). The name of the directory is taken from theIDprefix
parameter of themanage.create
action, with a sequential number appended.
Tip
threatware has not been tested with all git servers, so it may be necessary to manually create the default approved
branch as a one time setup activity.
Purpose
When
manage.indexdata
is called it returns status metadata about a threat model fromthreatmodels.yaml
file on theapproved
branch.manage.create
is called it creates acreate
branch and appends to the contents ofthreatmodels.yaml
a new threat model status metadata entry, and sets its status toDRAFT
. Multiple calls tomanage.create
append entries to the updatedthreatmodels.yaml
in thecreate
branch (so multiple calls tomanage.create
don’t end up with the same threat model ID).manage.submit
is calledit creates a branch with the name of the threat model ID (e.g.
CMP.TM.1
), andupdates the existing status metadata entry in
threatmodels.yaml
for a threat model toAPPROVED
, andadds or updates the directory named after the threat model ID (e.g.
CMP.TM.1
),adding/updating
metadata.yaml
with the version metadata of the submitted threat model, andadding the
1.0.yaml
and1.0.plain.yaml
model files (with appropriate version number in the name e.g. if the submitted threat model had approved version 3.2 the files would be called3.2.yaml
and3.2.plain.yaml
).
manage.measure
is called is readsthreatmodels.yaml
from theapproved
branch to find the approved version of the submitted threat model, then loads the full metadata version of the threat model (e.g.1.0.yaml
) from the repo, to use to compare against the current version of the threat model in the threat model document (passed in as a parameter tomanage.measure
).
Process
As the storage location holds the source of truth for the approval status of a threat model, but anyone in an organisation can invoke manage.create
and manage.submit
(only these 2 actions change the state of the storage location), there needs to be a process to ensure that only approved changes are recorded.
This is the purpose of the create
and threat model ID named (e.g. CMP.TM.1
) git repo branches. While anyone can cause entries on these branches to be created, only an approver should merge these changes onto the approved
branch, thus making any changes official.
There therefore needs to be a set of official approvers with permission to merge changes onto the approved
branch, usually the approvers would come from the Security Team in an origanisation. The exact process for notifiying approvers about threat model updates is not specified, but when an threat model author uses threatware manage.create
or manage.submit
the git server can usually be configured to notify a group of people about the change, who can then carry out a process (via a defined runbook for example) to review the requested change and approve it if it is acceptable.