• Threat model at speed,
    and scale.

  • Engage & educate developers.
    Fit into their workflows.

  • Generate reports,
    from code.

Continuous threat modelling, through code.

ThreatSpec is an open source project, and our mission is to do for security what unit testing and TDD has done for development.

Write code

Developers focus on doing what they do best: writing awesome code. And don't forget, when everything is code, everyone's a developer!

Annotate code

Developers and QA etc. add threat model comments to the source code, describing security-relevant decisions, concerns, and everything in between.

Peer review

The code and threat model comments are peer reviewed as usual. Security should be involved in the review process, even contributing changes back to developers.

Review dynamic reports

High and low-level threat model reports are automatically generated directly from code. Use CI/CD to generate and publish the reports.

Generate data flow diagrams

Automatically generate DFDs every time the code changes. Use these to drive further threat modelling activity, or even display them in the SOC.

Tighten feedback loops

Peer review and shared language encourages close collaboration between developers and security, helping to identify and fix security issues sooner.

Getting Started

How to use threatspec-go

This is a quick tutorial on using ThreatSpec for the Go language. We'll install threatspec-go and use it on the simple.go sample file.


You'll need Go

It's available here: https://golang.org/dl/

$ which go
$ go version
go version go1.7.5 linux/amd64

And Glide

It's available here: https://glide.sh/

$ which glide
$ glide --version
glide version v0.12.3

Install threatspec-go

Clone the GitHub repo

$ mkdir -p threatspec/go/src/github.com/threatspec
$ git clone https://github.com/threatspec/threatspec-go.git threatspec/go/src/github.com/threatspec/threatspec-go
Cloning into 'threatspec/go/src/github.com/threatspec/threatspec-go'...
remote: Counting objects: 100, done.
remote: Total 100 (delta 0), reused 0 (delta 0), pack-reused 100
Receiving objects: 100% (100/100), 1.00 MiB | 188.00 KiB/s, done.
Resolving deltas: 100% (44/44), done.
Checking connectivity... done.

Set up the Go environment

$ cd threatspec/go/
$ export GOPATH=$PWD

Install the dependencies using Glide

$ cd src/github.com/threatspec/threatspec-go/
$ glide install
[INFO]  Downloading dependencies. Please wait...
[INFO]  --> Found desired version locally github.com/xeipuuv/gojsonpointer e0fe6f68307607d540ed8eac07a342c33fa1b54a!
[INFO]  --> Found desired version locally github.com/xeipuuv/gojsonreference e02fc20de94c78484cd5ffb007f8af96be030a45!
[INFO]  --> Found desired version locally github.com/xeipuuv/gojsonschema f06f290571ce81ab347174c6f7ad2e1865af41a7!
[INFO]  Setting references.
[INFO]  --> Setting version for github.com/xeipuuv/gojsonpointer to e0fe6f68307607d540ed8eac07a342c33fa1b54a.
[INFO]  --> Setting version for github.com/xeipuuv/gojsonschema to f06f290571ce81ab347174c6f7ad2e1865af41a7.
[INFO]  --> Setting version for github.com/xeipuuv/gojsonreference to e02fc20de94c78484cd5ffb007f8af96be030a45.
[INFO]  Exporting resolved dependencies...
[INFO]  --> Exporting github.com/xeipuuv/gojsonpointer
[INFO]  --> Exporting github.com/xeipuuv/gojsonreference
[INFO]  --> Exporting github.com/xeipuuv/gojsonschema
[INFO]  Replacing existing vendor dependencies

Build the files

$ go build -o threatspec-go main.go
$ go build validator.go
$ go build report-ci.go
$ go build report-csv.go

Testing simple.go

If you take a quick look at the simple.go file, you'll see some of the functions have ThreatSpec comments above them. These are what we'll be reporting on.

// @accepts arbitrary file writes to WebApp:FileSystem with filename restrictions
// @mitigates WebApp:FileSystem against unauthorised access with strict file permissions
func (p *Page) save() error {
        filename := p.Title + ".txt"
        return ioutil.WriteFile(filename, p.Body, 0600)

Run threatspec-go

$ ./threatspec-go simple.go
ThreatSpec written to threatspec.json

Validate the intermediate JSON file

$ ./validator threatspec.json || echo 'There was a problem validating the json'

Run the sample CI report

$ ./report-ci threatspec.json
WARNING WebApp:App exposed to XSS injection by insufficient input validation in main.editHandler (simple.go:54)
WARNING WebApp:App exposed to content injection by insufficient input validation in main.saveHandler (simple.go:63)

Run the sample CSV report

$ ./report-csv threatspec.json
Writing report to threatspec.csv
$ cat threatspec.csv
WebApp,Web,resource access abuse,mitigation,basic input validation,main.makeHandler,simple.go,86
WebApp,Web,privilege escalation,mitigation,non-privileged port,main.main,simple.go,99
WebApp,FileSystem,unauthorised access,mitigation,strict file permissions,main.(*Page).save,simple.go,29
WebApp,App,XSS injection,exposure,insufficient input validation,main.editHandler,simple.go,54
WebApp,App,content injection,exposure,insufficient input validation,main.saveHandler,simple.go,63
User,Browser,@cwe_319_cleartext_transmission,transfer,non-sensitive information,main.main,simple.go,99
WebApp,FileSystem,arbitrary file writes,acceptance,filename restrictions,main.(*Page).save,simple.go,29
WebApp,FileSystem,arbitrary file reads,acceptance,filename restrictions,main.loadPage,simple.go,35

Coming soon!

A full end-to-end tutorial that starts with sketching an architecture, and goes on to writing code, threat modelling the code, and generating reports and DFDs.

Frequently Ask Questions

What is ThreatSpec?

ThreatSpec is an open source project that aims to close the gap between development and security by bringing the threat modelling process further into the development process. This is achieved by having developers and security engineers write threat specifications alongside code, then dynamically generating reports and data-flow diagrams from the code.

Security testing is shifting left, from annual pentests to the realm of unit testing and test-driven development, by taking advantage of automation and agile practices. ThreatSpec is an attempt to continue the evolution.

Is ThreatSpec free?

Yes! ThreatSpec code and tools are open source, so they're free to use, modify and distribute. The source code is available on Github.

How do I contribute or help out?

We're glad you asked!

Drop us an email to [email protected] or send a tweet to @ThreatSpec.

Anything you can do to help would be awesome. In particular, the following would be super helpful:

  • People to test TreatSpec, giving us feedback
  • Developers interested in adding support for more languages
  • Front-end devs to fix this site (it sucks)
  • People to spread the word, write documentation etc.

What is threat modelling?

Threat modeling is a process by which potential threats can be identified, enumerated, and prioritized – all from a hypothetical attacker’s point of view. The purpose of threat modeling is to provide defenders with a systematic analysis of the probable attacker’s profile, the most likely attack vectors, and the assets most desired by an attacker. Threat modeling answers the questions “Where are the high-value assets?” “Where am I most vulnerable to attack?” “What are the most relevant threats?” “Is there an attack vector that might go unnoticed?” [Wikipedia]

For a fully comprehensive introduction to threat modelling, check out the book Threat Modeling: Designing for Security by Adam Shostack.

What is code-driven threat modelling?

Threat modelling has traditionally been driven by the security team, either using general office tools like diagram drawing programs and spreadsheets, or using specialised threat modelling software. They'd either do it in isolation, based on architecture diagrams etc, or would have meetings with developers where they'd do threat modelling together at the beginning of the release.

ThreatSpec was created out of a need to threat model an open source security tool, where developers were distributed around the world in different time zones. Workflows were all centered around code, so it made sense to focus the threat modelling efforts around code, fitting into existing developer workflows. We wanted the threat model information to live along side the code, growing and changing with it. This way the threat model always stays in sync with the code, no matter how many MVPs or pivots there are.

We also wanted to create a continuous two-way conversation between developers and security. By having developers annotate their code with security information, we would be encouraging them to think about the security implications of their decisions as they went. We also wanted security to be in a position to peer review the changes in real time, taking advantage of code review systems and Continuous Integration / Continuous Deployment (CI/CD) tools.

And most importantly, we wanted security to be able to easily provide fast feedback to developers so that developers could benefit from continuous learning.

Are there any alternatives?

Many people just use whiteboards and standard office tools such as word processors, spreadsheets and diagram drawing applications. However, there are some threat modelling tools out there:

If you know of any more, let us know and we'll add them.