[opensourcedex]

threagile is a free, open source compliance & risk management project written in Go and released under MIT. It has 780 GitHub stars, 167 forks and 51 open issues, and was last pushed 5 months ago. On this registry it ranks #42 of 45 tracked projects in Compliance & Risk Management, with 5 head-to-head comparisons available.

What is threagile?

What it is

Threagile is an open-source Agile Threat Modeling Toolkit written in Go under the MIT license. It lives in the DevSecOps, information security, risk management, and agile architecture ecosystem, and it lets teams describe a software architecture and its assets as a YAML model inside an IDE.

The concrete problem it solves is the gap between architecture description and security analysis. The toolkit checks a YAML model against standard risk rules and any custom rules, then produces risk findings, diagrams, reports, and data files for review in an agile or CI/CD workflow.

Key capabilities

  • The toolkit models architecture and assets as YAML, so the threat model can be stored and edited in an IDE.
  • It checks standard risk rules and custom risk rules, and custom rules can be written as YAML scripts without compiling Go code.
  • It supports includes and macros, which help reduce repetitive YAML editing and make larger models easier to maintain.
  • It can generate a data asset diagram, a data-flow diagram, a report PDF, risks Excel, risks JSON, stats JSON, tags Excel, and technical assets JSON.
  • It provides commands, flags, and configuration options for creating example or stub models, creating editing support, listing macros, listing risk rules, and listing type information.
  • It can run as a command-line tool or start a server on a given port for one-off analysis or repeated execution.

Who uses it and how

  • Security architects and developers use Threagile to describe a system in YAML and run the toolkit to obtain risk findings and diagrams.
  • Agile and DevSecOps teams can use it in repeatable analysis workflows because the model is plain text and execution produces structured outputs.
  • Risk and compliance reviewers can use the generated PDF, Excel, JSON, and stats files to examine findings and share results.
  • Teams that need custom rules can write custom YAML risk rules and test them with the provided script testing documentation.

Getting started

The README presents Docker as the easiest execution method, using the image threagile/threagile with commands such as docker run --rm -it threagile/threagile --help. It also shows how to create an example model by mounting the current directory and running the image with --create-example-model and --out.

When to use it — and when not to

Threagile is a good fit when a team wants an open-source, MIT-licensed threat modeling tool that works from a YAML model and produces risk-rule findings, diagrams, and report files. It is less suitable when a team expects a finished graphical user interface, because the README says UI efforts are ongoing and not ready. The self-hoster mainly operates the Docker image, model files, rule files, and generated output artifacts; the provided facts do not mention a database, SMTP service, or hosted option.

project readme (upstream, from github) — read inline

Threagile

Threagile Community Chat

Agile Threat Modeling Toolkit

Threagile (see threagile.io for more details) is an open-source toolkit for agile threat modeling:

It allows to model an architecture with its assets in an agile fashion as a YAML file directly inside the IDE. Upon execution of the Threagile toolkit all standard risk rules (as well as individual custom rules if present) are checked against the architecture model. You can find more information about model schema here.

The tool have various commands and is highly configurable via flags and config.

We know that modifying yaml file via text editor may be tough and to simplify it we introduced:

Custom risk rules can be written as YAML scripts without compiling Go code. See the script language reference, the guide for writing custom risk rules, and how to test your scripts.

Efforts on UI are ongoing and there are few attempts to do it although that is far from being ready.

Here may be useful use cases on how others are using the tool and may be helpful to simplify onboarding of Threagile tool for your team.

Execution via Docker Container

The easiest way to execute Threagile on the commandline is via its Docker container:

    docker run --rm -it threagile/threagile --help

Which will give you an output with possible flags that can be used with Threagile.

      _____ _                          _ _
     |_   _| |__  _ __ ___  __ _  __ _(_) | ___
       | | | '_ \| '__/ _ \/ _` |/ _` | | |/ _ \
       | | | | | | | |  __/ (_| | (_| | | |  __/
       |_| |_| |_|_|  \___|\__,_|\__, |_|_|\___|
                                 |___/
    Threagile - Agile Threat Modeling


    Documentation: https://threagile.io
    Docker Images: https://hub.docker.com/r/threagile/threagile
    Sourcecode: https://github.com/threagile
    License: Open-Source (MIT License)
    Version: 1.0.0 (20231104141112)


    Usage: threagile [options]


    Options:

      -background string
        	background pdf file (default "background.pdf")
      -create-editing-support
        	just create some editing support stuff in the output directory
      -create-example-model
        	just create an example model named threagile-example-model.yaml in the output directory
      -create-stub-model
        	just create a minimal stub model named threagile-stub-model.yaml in the output directory
      -custom-risk-rules-plugins string
        	comma-separated list of plugins (.so shared object) file names with custom risk rules to load
      -diagram-dpi int
        	DPI used to render: maximum is 240 (default 120)
      -execute-model-macro string
        	Execute model macro (by ID)
      -generate-data-asset-diagram
        	generate data asset diagram (default true)
      -generate-data-flow-diagram
        	generate data-flow diagram (default true)
      -generate-report-pdf
        	generate report pdf, including diagrams (default true)
      -generate-risks-excel
        	generate risks excel (default true)
      -generate-risks-json
        	generate risks json (default true)
      -generate-stats-json
        	generate stats json (default true)
      -generate-tags-excel
        	generate tags excel (default true)
      -generate-technical-assets-json
        	generate technical assets json (default true)
      -ignore-orphaned-risk-tracking
        	ignore orphaned risk tracking (just log them) not matching a concrete risk
      -list-model-macros
        	print model macros
      -list-risk-rules
        	print risk rules
      -list-types
        	print type information (enum values to be used in models)
      -model string
        	input model yaml file (default "threagile.yaml")
      -output string
        	output directory (default ".")
      -print-3rd-party-licenses
        	print 3rd-party license information
      -print-license
        	print license information
      -server int
        	start a server (instead of commandline execution) on the given port
      -skip-risk-rules string
        	comma-separated list of risk rules (by their ID) to skip
      -verbose
        	verbose output
      -version
        	print version


    Examples:

    If you want to create an example model (via docker) as a starting point to learn about Threagile just run:
     docker run --rm -it -v "$(pwd)":/app/work threagile/threagile --create-example-model --output /app/work

    If you want to create a minimal stub model (via docker) as a starting point for your own model just run:
     docker run --rm -it -v "$(pwd)":/app/work threagile/threagile --create-stub-model --output /app/work

    If you want to execute Threagile on a model yaml file (via docker):
     docker run --rm -it -v "$(pwd)":/app/work threagile/threagile --verbose --model /app/work/threagile.yaml --output /app/work

    If you want to run Threagile as a server (REST API) on some port (here 8080):
     docker run --rm -it --shm-size=256m -p 8080:8080 --name threagile-server --mount 'type=volume,src=threagile-storage,dst=/data,readonly=false' threagile/threagile -server 8080

    If you want to find out about the different enum values usable in the model yaml file:
     docker run --rm -it threagile/threagile -list-types

    If you want to use some nice editing help (syntax validation, autocompletion, and live templates) in your favourite IDE:
     docker run --rm -it -v "$(pwd)":/app/work threagile/threagile --create-editing-support --output /app/work

    If you want to list all available model macros (which are macros capable of reading a model yaml file, asking you questions in a wizard-style and then update the model yaml file accordingly):
     docker run --rm -it threagile/threagile -list-model-macros

    If you want to execute a certain model macro on the model yaml file (here the macro add-build-pipeline):
     docker run --rm -it -v "$(pwd)":/app/work threagile/threagile --model /app/work/threagile.yaml --output /app/work --execute-model-macro add-build-pipeline

Releases

The information about releases can be found at releases page.

Contribution

You are very welcome to contribute into the project in any way. If you'd like to add new feature or fix the bug in the code base please follow contribution guide.

Otherwise please create GitHub discussion or issue and contributors will find some time to respond.

Frequently asked questions

Is threagile free to use?

threagile is open source under the MIT licence. There is no licence fee and no seat count — you can self-host it or, where the project offers one, pay a vendor for a managed version instead.

What does threagile do?

Agile Threat Modeling Toolkit

What is threagile written in?

threagile is primarily written in Go. Its source is publicly available at https://github.com/Threagile/threagile, and it has 780 GitHub stars.