Skip to content

Commit

Permalink
docs: Updating docs to 0.2.0
Browse files Browse the repository at this point in the history
  • Loading branch information
@xntrik
xntrik committed Mar 4, 2024
1 parent 338beb3 commit c470d1b
Show file tree
Hide file tree
Showing 4 changed files with 57 additions and 45 deletions.
8 changes: 8 additions & 0 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
@@ -1,3 +1,11 @@
## 0.2.0
### Mar 4, 2024

CHANGES:

* Renamed hcltm to threatcl
* Moved to a new org at github

## 0.1.8
### Mar 3, 2024

Expand Down
12 changes: 6 additions & 6 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
# How to contribute

Hi! I'm really happy you want to help out with `hcltm`. At this early stage, the best way to get started is to [Submit an Issue](https://github.com/xntrik/hcltm/issues) or [Submit a PR](https://github.com/xntrik/hcltm/pulls).
Hi! I'm really happy you want to help out with `threatcl`. At this early stage, the best way to get started is to [Submit an Issue](https://github.com/threatcl/threatcl/issues) or [Submit a PR](https://github.com/threatcl/threatcl/pulls).

I've been doing most of the work in the [dev](https://github.com/xntrik/hcltm/tree/dev) branch, and this is probably the best place to start looking at making changes.
I've been doing most of the work in the [dev](https://github.com/threatcl/threatcl/tree/dev) branch, and this is probably the best place to start looking at making changes.

## Testing

Expand All @@ -22,7 +22,7 @@ To check test coverage, the `make testcover` will open up the generated coverage

## Submitting changes

Please send a [GitHub Pull Request to hcltm](https://github.com/xntrik/hcltm/pulls) with a clear list of what you've done (read more about [pull requests](http://help.github.com/pull-requests/)). When you send a pull request, we will love you forever if you include tests as well. We can always use more test coverage. Please follow our coding conventions (below) and make sure all of your commits are atomic (one feature per commit).
Please send a [GitHub Pull Request to threatcl](https://github.com/threatcl/threatcl/pulls) with a clear list of what you've done (read more about [pull requests](http://help.github.com/pull-requests/)). When you send a pull request, we will love you forever if you include tests as well. We can always use more test coverage. Please follow our coding conventions (below) and make sure all of your commits are atomic (one feature per commit).

Always write a clear log message for your commits. One-line messages are fine for small changes, but bigger changes should look like this:

Expand Down Expand Up @@ -66,16 +66,16 @@ $ make bootstrap

## Releasing

All changes merged into the "main" branch will auto create a "Pre-release" https://github.com/xntrik/hcltm/releases
All changes merged into the "main" branch will auto create a "Pre-release" https://github.com/threatcl/threatcl/releases

To release a new version:
* Update all the references to the version number to the new version, particularly the [version](version/version.go) file.
* Update the [CHANGELOG](CHANGELOG.md)
* Once the main branch has been merged and updated and all the [actions](https://github.com/xntrik/hcltm/actions) are complete
* Once the main branch has been merged and updated and all the [actions](https://github.com/threatcl/threatcl/actions) are complete
* `git tag -a vN.N.N -m 'vN.N.N'`
* `git tag -f latest`
* `git push --tags`
* This should then run a "hcltm release" action to release a new version, including amd64/arm64 docker images to ghcr.io
* This should then run a "threatcl release" action to release a new version, including amd64/arm64 docker images to ghcr.io
* The following step is now redundant:
** From this repo, you need to push the new docker container (`VERSION=N.N.N TAG=latest make imagepush`) - this may take a while :grimace:
* From the https://github.com/xntrik/hcltm/pkgs/container/hcltm page, docker pull the two architectures locally
Expand Down
80 changes: 42 additions & 38 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,18 +1,22 @@
# hcltm
# threatcl

Threat Modeling with HCL

## What happened to hcltm?

hcltm has been renamed to `threatcl`. Welcome!

## Overview

There are many different ways in which a threat model can be documented. From a simple text file, to more in-depth word documents, to fully instrumented threat models in a centralised solution. Two of the most valuable attributes of a threat model are being able to clearly document the threats, and to be able to drive valuable change.

`hcltm` aims to provide a DevOps-first approach to documenting a [system threat model](https://owasp.org/www-community/Threat_Modeling) by focusing on the following goals:
`threatcl` aims to provide a DevOps-first approach to documenting a [system threat model](https://owasp.org/www-community/Threat_Modeling) by focusing on the following goals:

* Simple text-file format
* Simple cli-driven user experience
* Integration into version control systems (VCS)

This repository is the home of the `hcltm` cli software. The `hcltm` [spec](spec.hcl) is based on [HCL2](https://github.com/hashicorp/hcl/tree/hcl2), HashiCorp's Configuration Language, which aims to be "_pleasant to read and write for humans, and a JSON-based variant that is easier for machines to generate and parse_". Combining the `hcltm` cli software and the `hcltm` spec allows practitioners to define a system threat model in HCL, for example:
This repository is the home of the `threatcl` cli software. The `threatcl` [spec](spec.hcl) is based on [HCL2](https://github.com/hashicorp/hcl/tree/hcl2), HashiCorp's Configuration Language, which aims to be "_pleasant to read and write for humans, and a JSON-based variant that is easier for machines to generate and parse_". The `threatcl` spec lives at [github.com/threatcl/spec](https://github.com/threatcl/spec). Combining the `threatcl` cli software and the `threatcl` spec allows practitioners to define a system threat model in HCL, for example:

```hcl
threatmodel "Tower of London" {
Expand Down Expand Up @@ -65,34 +69,34 @@ You can also include an external threatmodel into your own, to reference and use
To see a full description of the spec, see [here](spec.hcl) or run:

```bash
hcltm generate boilerplate
threatcl generate boilerplate
```

`hcltm` will also process JSON files, but the only caveat is that import modules and variables won't work. You can see [examples/tm1.json](examples/tm1.json) as an example.
`threatcl` will also process JSON files, but the only caveat is that import modules and variables won't work. You can see [examples/tm1.json](examples/tm1.json) as an example.

## Why HCL?

HCL is the primary configuration language used in the products by HashiCorp, in-particularly, [Terraform](https://www.terraform.io/) - their open-source Infrastructure-as-Code software. I worked at HashiCorp for a while and the language really grew on me, plus, if DevOps and Software engineers are using the language, then simplifying how they document threat models aligns with `hcltm`'s goals.
HCL is the primary configuration language used in the products by HashiCorp, in-particularly, [Terraform](https://www.terraform.io/) - their open-source Infrastructure-as-Code software. I worked at HashiCorp for a while and the language really grew on me, plus, if DevOps and Software engineers are using the language, then simplifying how they document threat models aligns with `threatcl`'s goals.

You can use `hcltm` with JSON, but you lose some of the features. For more, see the [examples/](examples/) folder.
You can use `threatcl` with JSON, but you lose some of the features. For more, see the [examples/](examples/) folder.

## Why not just document them in MD?

I liked the idea of using a format that could be programmatically interacted with.

## Kudos and References

One of the features of `hcltm` is the automatic generation of [data flow diagrams](#data-flow-diagram) from HCL files. This leverages the [go-dfd](https://github.com/marqeta/go-dfd) package by Marqeta and [Blake Hitchcock](https://github.com/rbhitchcock). Definitely check out their blog post on [Threat models at the speed of DevOps](https://community.marqeta.com/t5/engineering-blogs/threat-models-at-the-speed-of-devops/ba-p/40).
One of the features of `threatcl` is the automatic generation of [data flow diagrams](#data-flow-diagram) from HCL files. This leverages the [go-dfd](https://github.com/marqeta/go-dfd) package by Marqeta and [Blake Hitchcock](https://github.com/rbhitchcock). Definitely check out their blog post on [Threat models at the speed of DevOps](https://community.marqeta.com/t5/engineering-blogs/threat-models-at-the-speed-of-devops/ba-p/40).

Additionally I'd like to extend thanks to [Jamie Finnigan](https://twitter.com/chair6) and [Talha Tariq](https://twitter.com/0xtbt) at HashiCorp for allowing me to continue working on this open-source tool even after I'd finished up with HashiCorp.

Also thanks to the IriusRisk folks for the [OpenThreatModel specification](https://github.com/iriusrisk/OpenThreatModel).

# hcltm cli
# threatcl cli

## Installation

Download the latest version from [releases](https://github.com/xntrik/hcltm/releases) and move the `hcltm` binary into your PATH.
Download the latest version from [releases](https://github.com/threatcl/threatcl/releases) and move the `threatcl` binary into your PATH.

## Install with Homebrew

Expand All @@ -115,19 +119,19 @@ docker run --rm -it xntrik/hcltm
## Building from Source

1. Clone this repository.
2. Change into the directory, `hcltm`
2. Change into the directory, `threatcl`
3. `make bootstrap`
4. `make dev`
4. `make build`

For further help on contributing to `hcltm` please see the [CHANGELOG.md](CHANGELOG.md).
For further help on contributing to `threatcl` please see the [CHANGELOG.md](CHANGELOG.md).

## Usage

For help on any subcommands use the `-h` flag.

```bash
$ hcltm
Usage: hcltm [--version] [--help] <command> [<args>]
$ threatcl
Usage: threatcl [--version] [--help] <command> [<args>]

Available commands are:
dashboard Generate markdown files from existing HCL threatmodel file(s)
Expand All @@ -142,7 +146,7 @@ Available commands are:

## (Optional) Config file

Most of the `hcltm` commands have a `-config` flag that allows you to specify a `config.hcl` file. HCL within this file may be used to overwrite some of `hcltm`'s default attributes. These are listed below:
Most of the `threatcl` commands have a `-config` flag that allows you to specify a `config.hcl` file. HCL within this file may be used to overwrite some of `threatcl`'s default attributes. These are listed below:

* **Initiative Sizes** - defaults to "Undefined", "Small", "Medium", "Large"
* **Default Initiative Size** - defaults to "Undefined
Expand Down Expand Up @@ -170,10 +174,10 @@ If you modify these attributes, you'll need to remember to provide the config fi

## List and View

The `hcltm list` and `hcltm view` commands can be used to list and view data from `hcltm` spec HCL files.
The `threatcl list` and `threatcl view` commands can be used to list and view data from `threatcl` spec HCL files.

```bash
$ hcltm list examples/*
$ threatcl list examples/*
# File Threatmodel Author
1 examples/tm1.hcl Tower of London @xntrik
2 examples/tm1.hcl Fort Knox @xntrik
Expand All @@ -182,32 +186,32 @@ $ hcltm list examples/*

## Validate

The `hcltm validate` command is used to validate a `hcltm` spec HCL file.
The `threatcl validate` command is used to validate a `threatcl` spec HCL file.

```bash
$ hcltm validate examples/*
$ threatcl validate examples/*
Validated 3 threatmodels in 3 files
```

## Export

The `hcltm export` command is used to export a `hcltm` threat model (or models) into the native JSON representation (by default), or into the [OTM](https://github.com/iriusrisk/OpenThreatModel) json representation. You can also directly save them into a file with the `-output` flag.
The `threatcl export` command is used to export a `threatcl` threat model (or models) into the native JSON representation (by default), or into the [OTM](https://github.com/iriusrisk/OpenThreatModel) json representation. You can also directly save them into a file with the `-output` flag.

```bash
$ hcltm export -format=otm examples/tm1.hcl
$ threatcl export -format=otm examples/tm1.hcl
[{"assets":[{"description":"including the imperial state crown","id":"crown-jewels","name":"crown jewels","risk":{"availability":0,"confidentiality":0,"integrity":0}}],"mitigations":[{"attributes":{"implementation_notes":"They are trained to be guards as well","implemented":true},"description":"Lots of guards patrol the area","id":"lots-of-guards","name":"Lots of Guards","riskReduction":80}],"otmVersion":"0.2.0","project":{"attributes":{"initiative_size":"Small","internet_facing":true,"network_segment":"dmz","new_initiative":true},"description":"A historic castle","id":"tower-of-london","name":"Tower of London","owner":"@xntrik"},"threats":[{"categories":["Confidentiality"],"description":"Someone who isn't the Queen steals the crown","id":"threat-1","name":"Threat 1","risk":{"impact":0,"likelihood":null}}]},{"assets":[{"description":"Lots of gold","id":"gold","name":"Gold","risk":{"availability":0,"confidentiality":0,"integrity":0}}],"mitigations":[{"attributes":{"implemented":true},"description":"A large wall surrounds the fort","id":"big-wall","name":"Big Wall","riskReduction":80}],"otmVersion":"0.2.0","project":{"attributes":{"initiative_size":"Small","internet_facing":true,"new_initiative":false},"description":"A .. fort?","id":"fort-knox","name":"Fort Knox","owner":"@xntrik"},"threats":[{"categories":["Confidentiality"],"description":"Someone steals the gold","id":"threat-1","name":"Threat 1","risk":{"impact":0,"likelihood":null}}]}]
```

## Generate

The `hcltm generate` command is used to either output a generic `boilerplate` `hcltm` spec HCL file, or, interactively ask the user questions to then output a `hcltm` spec HCL file.
The `threatcl generate` command is used to either output a generic `boilerplate` `threatcl` spec HCL file, or, interactively ask the user questions to then output a `threatcl` spec HCL file.

### Generate Interactive

See the following example of:

```bash
hcltm generate interactive
threatcl generate interactive
```

<p align="center">
Expand All @@ -219,17 +223,17 @@ hcltm generate interactive
If you prefer to work directly in your `$EDITOR` then run:

```bash
hcltm generate interactive editor
threatcl generate interactive editor
```

This will open your editor with a barebones HCL threat model. If you want to validate the model after creation, then use the `-validate` flag.

## Dashboard

The `hcltm dashboard` command takes `hcltm` spec HCL files, and generates a number of markdown and png files, dropping them into a selected folder.
The `threatcl dashboard` command takes `threatcl` spec HCL files, and generates a number of markdown and png files, dropping them into a selected folder.

```bash
$ hcltm dashboard -overwrite -outdir=dashboard-example examples/*
$ threatcl dashboard -overwrite -outdir=dashboard-example examples/*
Created the 'dashboard-example' directory
Writing dashboard markdown files to 'dashboard-example' and overwriting existing files
Successfully wrote to 'dashboard-example/tm1-toweroflondon.md'
Expand All @@ -241,41 +245,41 @@ Successfully wrote to 'dashboard-example/dashboard.md'

### Custom Markdown Templates

The `hcltm dashboard` command can also take optional flags to specify custom templates (as per Golang's [text/template](https://pkg.go.dev/text/template)).
The `threatcl dashboard` command can also take optional flags to specify custom templates (as per Golang's [text/template](https://pkg.go.dev/text/template)).

To specify a dashboard template file, use the `-dashboard-template` flag. For an example, see [dashboard-template.tpl](examples/dashboard-template.tpl).

To specify a threatmodel template file, use the `-threatmodel-template` flag. For an example, see [threatmodel-template.tpl](examples/threatmodel-template.tpl).

### Custom Filename for the Dashboard Index file

The `hcltm dashboard` command can also take an optional flag to specify a filename for the "index" generated dashboard file. By default this file is `dashboard.md`. Use the `-dashboard-filename` flag without an extension to change this filename.
The `threatcl dashboard` command can also take an optional flag to specify a filename for the "index" generated dashboard file. By default this file is `dashboard.md`. Use the `-dashboard-filename` flag without an extension to change this filename.

## Data Flow Diagram

As per the [spec](spec.hcl), a `threatmodel` may include `data_flow_diagram_v2` blocks. An example of a simple DFD is available [here](examples/tm2.hcl). The old, single-use-block `data_flow_diagram` will be deprecated at some point, so it's better to use `data_flow_diagram_v2` named blocks, that way you can have multiple associated DFDs.

The `hcltm dfd` command takes `hcltm` spec HCL files, and generates a number of png files, dropping them into a selected folder.
The `threatcl dfd` command takes `threatcl` spec HCL files, and generates a number of png files, dropping them into a selected folder.

If the HCL file doesn't include a `threatmodel` block with a `data_flow_diagram` or `data_flow_diagram_v2` block, then nothing is output.

The command itself is very similar to the Dashboard command.

```bash
$ hcltm dfd -overwrite -outdir testout examples/*
$ threatcl dfd -overwrite -outdir testout examples/*
Successfully created 'testout/tm2-modellymodel.png'
```

If your `threatmodel` doesn't include a `diagram_link`, but does include a `data_flow_diagram`, then this will also be rendered when running `hcltm dashboard`.
If your `threatmodel` doesn't include a `diagram_link`, but does include a `data_flow_diagram`, then this will also be rendered when running `threatcl dashboard`.

## Terraform

The `hcltm terraform` command is able to extract data resources from the `terraform show -json` [docs here](https://www.terraform.io/docs/cli/commands/show.html) output of plan files, or active state files, and convert these into drafted `information_asset` blocks for inclusion in `hcltm` files.
The `threatcl terraform` command is able to extract data resources from the `terraform show -json` [docs here](https://www.terraform.io/docs/cli/commands/show.html) output of plan files, or active state files, and convert these into drafted `information_asset` blocks for inclusion in `threatcl` files.

If you're in a folder with existing state, you can execute the following:

```bash
terraform show -json | hcltm terraform -stdin
terraform show -json | threatcl terraform -stdin
```

This will output something similar to this:
Expand All @@ -296,17 +300,17 @@ information_asset "aws_s3_bucket example" {
You can also see similar output from a plan file that hasn't yet been applied with Terraform by running:

```bash
terraform show -json <plan-file> | hcltm terraform -stdin
terraform show -json <plan-file> | threatcl terraform -stdin
```

If you want to update an existing `hcltm` threat model file ("threatmodel.hcl") you can with:
If you want to update an existing `threatcl` threat model file ("threatmodel.hcl") you can with:

```bash
terraform show -json <plan> | hcltm terraform -stdin -add-to-existing=threatmodel.hcl > new-threatmodel.hcl
terraform show -json <plan> | threatcl terraform -stdin -add-to-existing=threatmodel.hcl > new-threatmodel.hcl
```

With the `-add-to-existing` flag, you can also specify `-tm-name=<string>` if you need to specify a particular threat model from the source file, if there are multiple. And you can also apply a default classification, with the `-default-classification=Confidential` flag.

These commands can also take a file as input too, in which case, omit the `-stdin` flag.

The terraform resources that `hcltm` is aware of are hard coded in [pkg/terraform/terraform.go](pkg/terraform/terraform.go). If you want the `hcltm terraform` command to output other `information_asset` resources that aren't in there, you can supply your own version of this json via the `-tf-collection=<json file>` flag.
The terraform resources that `threatcl` is aware of are hard coded in [pkg/terraform/terraform.go](pkg/terraform/terraform.go). If you want the `threatcl terraform` command to output other `information_asset` resources that aren't in there, you can supply your own version of this json via the `-tf-collection=<json file>` flag.
2 changes: 1 addition & 1 deletion version/version.go
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
package version

const (
Version string = "0.1.8"
Version string = "0.2.0"
)

func GetVersion() string {
Expand Down

0 comments on commit c470d1b

Please sign in to comment.