Documenting your Threat Models with HCL

Related tags

Miscellaneous hcltm
Overview

hcltm

Threat Modeling with HCL

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 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 is based on 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:

threatmodel "Tower of London" {
  description = "A historic castle"
  author = "@xntrik"

  attributes {
    new_initiative = "true"
    internet_facing = "true"
    initiative_size = "Small"
  }

  information_asset "crown jewels" {
    description = "including the imperial state crown"
    information_classification = "Confidential"
  }

  usecase {
    description = "The Queen can fetch the crown"
  }

  third_party_dependency "community watch" {
    description = "The community watch helps guard the premise"
    uptime_dependency = "degraded"
  }

  threat {
    description = "Someone who isn't the Queen steals the crown"
    impacts = ["Confidentiality"]
    control = "Lots of guards"
  }

  data_flow_diagram {
    // ... see below for more information
  }

}

See Data Flow Diagram for more information on how to construct data flow diagrams that are converted to PNGs automatically.

To see an example of how to reference pre-defined control libraries for the OWASP Proactive Controls and AWS Security Checklist see examples/tm3.hcl

To see a full description of the spec, see here or run:

$ hcltm 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 as an example.

Why HCL?

HCL is the primary configuration language used in the products by HashiCorp, in-particularly, Terraform - 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.

You can use hcltm with JSON, but you lose some of the features. For more, see the 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 from HCL files. This leverages the go-dfd package by Marqeta and Blake Hitchcock. Definitely check out their blog post on Threat models at the speed of DevOps.

Additionally I'd like to extend thanks to Jamie Finnigan and Talha Tariq at HashiCorp for allowing me to continue working on this open-source tool even after I'd finished up with HashiCorp.

hcltm cli

Installation

Download the latest version from releases and move the hcltm binary into your PATH.

Run with Docker

$ docker run --rm -it xntrik/hcltm

Run with GitHub Actions

hcltm can be integrated directly into your GitHub repos with https://github.com/xntrik/hcltm-action. This is one of the ideal methods to manage your threat models, and helps meet the goal of integrating into your version control systems.

Building from Source

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

For further help on contributing to hcltm please see the CHANGELOG.md.

Usage

For help on any subcommands use the -h flag.

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

Available commands are:
    dashboard    Generate markdown files from existing HCL threatmodel file(s)
    dfd          Generate Data Flow Diagram PNG files from existing HCL threatmodel file(s)
    generate     Generate an HCL Threat Model
    list         List Threatmodels found in HCL file(s)
    validate     Validate existing HCL Threatmodel file(s)
    view         View existing HCL Threatmodel file(s)

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:

  • Initiative Sizes - defaults to "Undefined", "Small", "Medium", "Large"
  • Default Initiative Size - defaults to "Undefined
  • Information Classifications - defaults to "Restricted", "Confidential", "Public"
  • Default Information Classification - defaults to "Confidential"
  • Impact Types - defaults to "Confidentiality", "Integrity", "Availability"
  • STRIDE Elements - defaults to "Spoofing", "Tampering", "Info Disclosure", "Denial Of Service", "Elevation Of Privilege"
  • Uptime Dependency Classifications - defaults to "none", "degraded", "hard", "operational"
  • Default Uptime Depency Classification - defaults to "none"

For example:

initiative_sizes = ["S", "M", "L"]
default_initiative_size = "M"
info_classifications = ["1", "2"]
default_info_classification = "1"
impact_types = ["big", "small"]
strides = ["S", "T"]
uptime_dep_classifications = ["N", "D"]
default_uptime_dep_classification = "N"

If you modify these attributes, you'll need to remember to provide the config file for other operations, as this may impact validation or dashboard creation.

List and View

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

$ hcltm list examples/*
#  File              Threatmodel      Author
1  examples/tm1.hcl  Tower of London  @xntrik
2  examples/tm1.hcl  Fort Knox        @xntrik
3  examples/tm2.hcl  Modelly model    @xntrik

Validate

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

$ hcltm validate examples/*
Validated 3 threatmodels in 3 files

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.

Generate Interactive

See the following example of:

$ hcltm generate interactive

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.

$ hcltm 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'
Successfully wrote to 'dashboard-example/tm1-fortknox.md'
Successfully wrote to 'dashboard-example/tm2-modellymodel.png'
Successfully wrote to 'dashboard-example/tm2-modellymodel.md'
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).

To specify a dashboard template file, use the -dashboard-template flag. For an example, see dashboard-template.tpl.

To specify a threatmodel template file, use the -threatmodel-template flag. For an example, see 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.

Data Flow Diagram

As per the spec, a threatmodel may include a single data_flow_diagram. An example of a simple DFD is available here.

The hcltm dfd command takes hcltm 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 block, then nothing is output.

The command itself is very similar to the Dashboard command.

$ hcltm 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.

Issues
Releases(latest)
Owner
Christian Frichot
Christian Frichot
Modeling-epidemics - Models the spread of epidemics using SEIR

Modeling Epidemics Using The SEIR Model PROBELM AND MOTIVATION Epidemics are tri

null 0 Dec 31, 2021
🧀 Formaggo is a simple model checker inspired by TLA+, The checker and the models are written in Go

?? Formaggo. A cheesy exhaustive state checker in Go. Formaggo is a simple model checker inspired by TLA+. The checker and the models are written in G

Jakub Mikians 0 Jan 23, 2022
Host yo' self from your browser, your phone, your toaster.

A hosting service from the browser, because why not. Try it at hostyoself.com. See it in action Here's an example where I use hostyoself.com to host i

Zack 1.7k Jun 28, 2022
James is your butler and helps you to create, build, debug, test and run your Go projects

go-james James is your butler and helps you to create, build, debug, test and run your Go projects. When you often create new apps using Go, it quickl

Pieter Claerhout 50 Mar 8, 2022
An easy way to add useful startup banners into your Go applications

Try browsing the code on Sourcegraph! Banner Add beautiful banners into your Go applications Table of Contents Motivation Usage API Command line flags

Claudemiro 396 Jun 23, 2022
:mailbox_closed: Your own local SMS gateway in Go

gosms Your own local SMS gateway What's the use ? Can be used to send SMS, where you don't have access to internet or cannot use Web SMS gateways or w

null 1.4k Jun 22, 2022
:guardsman: A teeny tiny and somewhat opinionated generator for your next golang project

A Yeoman Golang Generator We are very sorry Gophers, but other names for the generator where taken, so we choose go-lang. But we have gocreate as an a

Axel Springer SE 24 Jun 17, 2022
GoThanks automatically stars Go's official repository and your go.mod github dependencies, providing a simple way to say thanks to the maintainers of the modules you use and the contributors of Go itself.

Give thanks (in the form of a GitHub ★) to your fellow Go modules maintainers. About GoThanks performs the following operations Sends a star to Go's r

psampaz 112 Jun 12, 2022
Automatically generate Go test boilerplate from your source code.

gotests gotests makes writing Go tests easy. It's a Golang commandline tool that generates table driven tests based on its target source files' functi

Charles Weill 4k Jul 1, 2022
Yubigo is a Yubikey client API library that provides an easy way to integrate the Yubico Yubikey into your existing Go-based user authentication infrastructure.

yubigo Yubigo is a Yubikey client API library that provides an easy way to integrate the Yubikey into any Go application. Installation Installation is

Geert-Johan Riemer 119 Apr 28, 2022
An HTTP service for customizing import path of your Go packages.

Go Packages A self-host HTTP service that allow customizing your Go package import paths. Features Reports. Badges. I18N. Preview I launch up a free H

Razon Yang 18 Nov 18, 2021
Enable your Golang applications to self update with S3

s3update Enable your Golang applications to self update with S3. Requires Go 1.8+ This package enables our internal tools to be updated when new commi

Heetch 104 Jun 22, 2021
Give your dependencies stars on GitHub! 🌟

Give stars to your dependencies of Go repositories and say thank you to developers!!

Kensei Nakada 19 May 29, 2022
Auto-evaluate your Golang code.

Ginker Ginker is a GUI application for auto-evaluating your Golang code. It allows you to write and run Golang code on the fly and it will help you to

nkoporec 8 Jun 24, 2021
Default godoc generator - make your first steps towards better code documentation

godoc-generate Overview godoc-generate is a simple command line tool that generates default godoc comments on all exported types, functions, consts an

Dimitar Petrov 18 Nov 14, 2021
Hack this repo and add your name to the list above. Creativity and style encouraged in both endeavors.

Hack this repo and add your name to the list above. Creativity and style encouraged in both endeavors.

Danger 2 Oct 1, 2021
Shows your recent browser history in tree style. 树状展示浏览器历史 (For Edge / Chromium / Chrome)

Tree Style Histyle This extension shows your recent browser history in tree style. When you browser pages from internet, you always jump from one page

null 123 Jun 23, 2022
Package fsm allows you to add finite-state machines to your Go code.

fsm Package fsm allows you to add finite-state machines to your Go code. States and Events are defined as int consts: const ( StateFoo fsm.State =

Cocoon Space 25 Jul 1, 2022
Don't get surprised by your environment variables.

checkenv Don't get surprised by your environment variables. Rationale At Bugout, we configure our applications using environment variables. This follo

Bugout.dev 2 Dec 20, 2021