dist/

FROM golang:1.19-alpine3.16@sha256:4e2a54594cfe7002a98c483c28f6f3a78e5c7f4010c355a8cf960292a3fdecfe AS builder

ARG VERSION=dev-snapshot

RUN mkdir /build

RUN apk add --update make

WORKDIR /build

ADD . /build

RUN make BUILD_VERSION=${VERSION}

FROM alpine:3.16@sha256:3d426b0bfc361d6e8303f51459f17782b219dece42a1c7fe463b6014b189c86d AS runner

LABEL org.opencontainers.image.source="https://github.com/DataDog/threatest/"

COPY --from=builder /build/bin/threatest /threatest

ENTRYPOINT ["/threatest"]

CMD ["--help"]

.PHONY: mocks parser

all: build

build:

mkdir -p bin

go build -o bin/threatest cmd/threatest/*.go

$${GOPATH}/bin/go-licenses csv github.com/datadog/threatest/pkg/threatest | sort > $(ROOT_DIR)/LICENSE-3rdparty.csv

parser:

go get github.com/atombender/go-jsonschema/...

go install github.com/atombender/go-jsonschema/cmd/gojsonschema@latest

$${GOPATH}/bin/gojsonschema -p parser schemas/threatest.schema.json > pkg/threatest/parser/parser.go

Threatest comes with a CLI that you can use to run test scenarios described as YAML, following a specific [schema](./schemas/threatest.schema.json). You can configure this schema in your editor to benefit from in-IDE linting and autocompletion (see [documentation for VSCode](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml#associating-a-schema-to-a-glob-pattern-via-yaml.schemas) using the [YAML](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml) extension).

Sample usage:

$ threatest lint scenarios.threatest.yaml

All 6 scenarios are syntaxically valid

$ threatest run local-scenarios.threatest.yaml

$ threatest run scenarios.threatest.yaml --ssh-host test-box --ssh-username vagrant

$ export THREATEST_SSH_HOST=test-box

$ export THREATEST_SSH_USERNAME=vagrant

$ threatest run scenarios.threatest.yaml

Sample scenario definition file:

scenarios:

- description: curl metadata service

detonate:

remoteDetonator:

commands: ["curl http://169.254.169.254 --connect-timeout 1"]

expectations:

- timeout: 1m

datadogSecuritySignal:

name: "Network utility accessed cloud metadata service"

severity: medium

- description: running nmap

detonate:

remoteDetonator:

commands:

- "which nmap || sudo apt install -y nmap"

- "nmap -sn 172.16.2.1/32 -T5"

expectations:

- timeout: 1m

datadogSecuritySignal:

name: Network scanning utility executed

{

"description": "change user password",

"isSuccess": true,

"errorMessage": "",

"durationSeconds": 22.046627348,

"timeDetonated": "2022-11-15T22:26:14.182844+01:00"

},

{

"description": "adding an SSH key",

"isSuccess": true,

"errorMessage": "",

"durationSeconds": 23.604699625,

"timeDetonated": "2022-11-15T22:26:14.182832+01:00"

},

{

"description": "change user password",

"isSuccess": false,

"errorMessage": "At least one scenario failed:\n\nchange user password returned: change user password: 1 assertions did not pass\n =\u003e Did not find Datadog security signal 'bar'\n",

"durationSeconds": 3.505294235,

"timeDetonated": "2022-11-15T22:26:36.229349+01:00"

}

By default, scenarios are run with a maximum parallelism of 5. You can increase this setting using the `--parallelism` argument.

Note that when using remote SSH detonators, each scenario running establishes a new SSH connection.

See [examples](./examples) for complete programmatic usage example.

package main

import (

"errors"

"fmt"

"github.com/datadog/threatest/pkg/threatest"

"github.com/datadog/threatest/pkg/threatest/parser"

log "github.com/sirupsen/logrus"

"github.com/spf13/cobra"

"os"

)

type LintCommand struct {

InputFiles []string

}

func (m *LintCommand) Do() error {

if len(m.InputFiles) == 0 {

return errors.New("please provide at least 1 scenario")

}

var numScenarios = 0

for _, inputFile := range m.InputFiles {

rawScenario, err := os.ReadFile(inputFile)

if err != nil {

return fmt.Errorf("unable to read input file %s: %v", inputFile, err)

}

scenarios, err := parser.Parse(rawScenario, "unused", "", "")

if err != nil {

return fmt.Errorf("unable to parse input file %s: %v", inputFile, err)

}

for _, scenario := range scenarios {

if err := validateScenario(scenario); err != nil {

return fmt.Errorf("invalid scenario '%s': %s", scenario.Name, err.Error())

}

}

numScenarios += len(scenarios)

}

log.Infof("All %d scenarios are syntaxically valid", numScenarios)

return nil

}

func validateScenario(scenario *threatest.Scenario) error {

if scenario.Detonator == nil {

return errors.New("no detonator defined")

}

if len(scenario.Assertions) == 0 {

return errors.New("no assertion defined")

}

return nil

}

func NewLintCommand() *cobra.Command {

lintCmd := &cobra.Command{

Use: "lint",

Short: "Validate the format of scenarios",

SilenceUsage: true,

Example: "lint /path/to/scenario/1 [/path/to/scenario/2]...",

RunE: func(cmd *cobra.Command, args []string) error {

command := LintCommand{

InputFiles: args,

}

return command.Do()

},

}

return lintCmd

}

package main

import (

"github.com/spf13/cobra"

"os"

)

var rootCmd = &cobra.Command{

Use: "threatest",

}

func init() {

rootCmd.AddCommand(NewRunCommand())

rootCmd.AddCommand(NewLintCommand())

}

func main() {

if err := rootCmd.Execute(); err != nil {

os.Exit(1)

}

}