StartLeft

https://iriusrisk.github.io/startleft
Admin
StartLeft is an automation tool for generating Open Threat Model (OTM) files from various sources...
Tokens:138,324
Snippets:784
Trust Score:9.7
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Install StartLeft with setup and test extras

Source: https://iriusrisk.github.io/startleft/development/Quickstart-Guide-for-Developers

Installs all required dependencies, including those for setup and testing, into the active virtual environment.

```bash
pip install -e ".[setup,test]"

```

--------------------------------

### Start StartLeft server locally

Source: https://iriusrisk.github.io/startleft/integration/Quickstart-Guide-for-Integrations

Starts the StartLeft service on default port 5000. Requires StartLeft installed as explained in the Quickstart Guide for Beginners.

```bash
startleft server
```

--------------------------------

### Startleft server example with CLI and output

Source: https://iriusrisk.github.io/startleft/usage/Command-Line-Interface

Starts the Startleft server on port 5000. The output shows the server startup logs including the Uvicorn URL where the server is running.

```bash
startleft server \
--port 5000


```

```text
INFO    cli - Startleft version: 1.10.0
INFO    server - Started server process []
INFO    on - Waiting for application startup.
INFO    on - Application startup complete.
INFO    server - Uvicorn running on http://127.0.0.1:5000 (Press CTRL+C to quit)


```

--------------------------------

### Download an example OTM file

Source: https://iriusrisk.github.io/startleft/Quickstart-Guide-for-Beginners

Downloads an example OTM file from the StartLeft repository's examples/otm folder.

```bash
wget https://raw.githubusercontent.com/iriusrisk/startleft/main/examples/otm/manual_threat_model.otm

```

--------------------------------

### Download example Terraform file

Source: https://iriusrisk.github.io/startleft/Quickstart-Guide-for-Beginners

Download an example Terraform file from the StartLeft repository.

```bash
wget https://raw.githubusercontent.com/iriusrisk/startleft/main/examples/terraform/multinetwork_security_groups_with_lb.tf
```

--------------------------------

### Start the StartLeft server

Source: https://iriusrisk.github.io/startleft/development/Quickstart-Guide-for-Developers

Starts the StartLeft server. If the environment is configured correctly, it should start without errors in the logs.

```bash
startleft server

```

--------------------------------

### Run StartLeft CLI for Visio diagram

Source: https://iriusrisk.github.io/startleft/startleft-processors/diagram/visio/Visio-Quickstart

CLI command to run StartLeft on a Visio diagram. Requires StartLeft installed and the files visio-basic-example.vsdx, default-mapping.yaml, and custom-mapping.yaml in the working directory. Generates basic-visio-example.otm with contents identical to the example above.

```bash
startleft parse \
    --diagram-type VISIO \
    --default-mapping-file default-mapping.yaml \
    --custom-mapping-file custom-mapping.yaml \
    --output-file basic-visio-example.otm \
    --project-id "my-visio-basic-example" \
    --project-name "My Visio Basic Example" \
    visio-basic-example.vsdx
```

--------------------------------

### Install StartLeft with pip

Source: https://iriusrisk.github.io/startleft/Quickstart-Guide-for-Beginners

Install the latest stable version of StartLeft using pip.

```bash
pip install git+https://github.com/iriusrisk/startleft.git
```

--------------------------------

### Parse CLI example

Source: https://iriusrisk.github.io/startleft/usage/Command-Line-Interface

Example of the startleft parse command with CLI arguments for VISIO diagram type and default mapping file. It produces the OTM output file 'visio-basic-example.otm'.

```bash
startleft parse \
--diagram-type VISIO \
--default-mapping-file iriusrisk-visio-aws-mapping.yaml \
--output-file visio-basic-example.otm \
--project-name "VISIO Basic Example" \
--project-id "vs-bs-ex" \
visio-basic-example.vsdx
```

```text
Parsing source files into OTM
Parsing diagram source files into OTM
Validating visio file
Mapping file size is valid
Loading schema file 'diagram_mapping_schema.json'
Mapping files are valid
Mapping files are valid
Mapping file size is valid
Loading mapping data
Loading schema file 'otm_schema.json'
OTM file schema is valid
OTM file has consistent IDs
OTM file validated successfully
Writing OTM file to 'visio-basic-example.otm'
```

--------------------------------

### StartLeft Server Startup Commands

Source: https://iriusrisk.github.io/startleft/startleft-processors/iac/cft/CloudFormation-Quickstart

Commands to start the StartLeft REST API server. The first starts the server on the default port; the second starts it on port 8080.

```bash
startleft server

```

```bash
startleft server -p 8080

```

--------------------------------

### Visio summary output example

Source: https://iriusrisk.github.io/startleft/startleft-processors/diagram/visio/Visio-Summary

Example output of the summary tool, showing a table with source file, element type, element name, and mapped OTM type for each shape.

```text
| SOURCE      | SOURCE_ELEMENT_TYPE | SOURCE_ELEMENT_NAME   | OTM_MAPPED_TYPE |
|-------------|---------------------|-----------------------|-----------------|
| file_1.vsdx |                     | Public Cloud          |                 |
| file_1.vsdx |                     | Custom VPC            |                 |
| file_1.vsdx |                     | Private Secured Cloud |                 |
| file_1.vsdx | Amazon CloudWatch   | Amazon CloudWatch     | cloudwatch      |
| file_1.vsdx | Amazon CloudWatch   | Custom log system     | cloudwatch      |
| file_1.vsdx | Amazon EC2          | Amazon EC2            | ec2             |
| file_1.vsdx | Amazon EC2          | Custom machine        | ec2             |
| file_1.vsdx | Database            | Private Database      | rds             |
| file_2.vsdx |                     | Private Secured Cloud |                 |
| file_2.vsdx |                     | Public Cloud          |                 |
| file_2.vsdx |                     | My Custom VPC         |                 |
| file_2.vsdx |                     | My Custom Machine     |                 |
| file_2.vsdx | Amazon EC2          | My EC2                | ec2             |
| file_2.vsdx | Database            | Private Database      | rds             |

```

--------------------------------

### Start StartLeft server on custom port

Source: https://iriusrisk.github.io/startleft/integration/Quickstart-Guide-for-Integrations

Starts the StartLeft service with a custom port using the --port/-p modifier. Default port is 5000.

```bash
startleft server --port 8080
```

--------------------------------

### Example OTM snippet (parse context)

Source: https://iriusrisk.github.io/startleft/usage/Command-Line-Interface

A brief OTM example showing a parse result with project name, id, representations, trust zones, and components.

```json
{
  "otmVersion": "0.1.0",
  "project": {
    "name": "cft_multiple_files_project",
    "id": "cft_multiple_files_project_id"
  },
  "representations": [
    {
      "name": "CloudFormation",
      "id": "CloudFormation",
      "type": "code"
    }
  ],
  "trustZones": [
    {
      "id": "b61d6911-338d-46a8-9f39-8dcd24abfe91",
      "name": "Public Cloud",
      "risk": {
        "trustRating": 10
      }
    },
    {
      "id": "f0ba7722-39b6-4c81-8290-a30a248bb8d9",
      "name": "Internet",
      "risk": {
        "trustRating": 10
      }
    }
  ],
  "components": [
    {
      "id": "b61d6911-338d-46a8-9f39-8dcd24abfe91.customvpc",
      "name": "CustomVPC",
      "type": "vpc",
      "parent": {
        "trustZone": "b61d6911-338d-46a8-9f39-8dcd24abfe91"
      },
      "tags": [
        "AWS::EC2::VPC"
      ]
    },
    {
      "id": "b61d6911-338d-46a8-9f39-8dcd24abfe91.customvpc.privatesubnet1",
      "name": "PrivateSubnet1",
      "type": "empty-component",
      "parent": {
        "component": "b61d6911-338d-46a8-9f39-8dcd24abfe91.customvpc"
      },
      "tags": [
        "AWS::EC2::Subnet"
      ]
    }
  ]
}
```

--------------------------------

### Launch StartLeft documentation with mkdocs serve

Source: https://iriusrisk.github.io/startleft/About

Install documentation dependencies and serve the docs with mkdocs for automatic reloading on changes.

```bash
pip install -r docs/requirements.txt
mkdocs serve

```

--------------------------------

### Health endpoint example (curl request and response)

Source: https://iriusrisk.github.io/startleft/usage/REST-API

Example curl request to GET /health and its JSON response showing status, version, and components.

```bash
curl localhost:5000/health
```

```json
{
    "status": "OK",
    "version": "1.10.0",
    "components": {
        "StartLeft": "OK"
    }
}
```

--------------------------------

### Launch StartLeft documentation with docker-compose (plugin)

Source: https://iriusrisk.github.io/startleft/About

Deploy the documentation using the docker-compose plugin from the deployment folder.

```bash
cd deployment
docker-compose up -d startleft-docs

```

--------------------------------

### $root mapping function example with JMESPath get

Source: https://iriusrisk.github.io/startleft/startleft-processors/iac/tf/Terraform-domain-specific-language

Mapping file example for the $root mapping function. It uses the JMESPath expression "resource|get(@, 'aws_vpc')" to filter the entire source file and map the aws_vpc resource to a component of type vpc. The example includes the Terraform resource definition and the resulting OTM representation.

```yaml
trustzones:
  - id:   public-cloud-01
    name: Public Cloud
    type: b61d6911-338d-46a8-9f39-8dcd24abfe91
    $default: true
components:
  - type:        vpc
    $source:     {$root: "resource|get(@, 'aws_vpc')"}
dataflows: []

```

```hcl
resource "aws_vpc" "CustomVPC" {
  cidr_block  = var.vpcCidrblock
}

```

```yaml
---
otmVersion: 0.1.0
project:
  name: name
  id: id
representations:
  - name: Terraform
    id: Terraform
    type: code
trustZones:
  - id: public-cloud-01
    name: Public Cloud
    type: b61d6911-338d-46a8-9f39-8dcd24abfe91
    risk:
      trustRating: 10
components:
  - id: public-cloud-01.aws_vpc-customvpc
    name: CustomVPC
    type: vpc
    parent:
      trustZone: public-cloud-01
    tags:
      - aws_vpc
dataflows: []

```

--------------------------------

### Launch StartLeft documentation with docker compose (standalone)

Source: https://iriusrisk.github.io/startleft/About

Deploy the documentation using the standalone docker compose command from the deployment folder.

```bash
cd deployment
docker compose up -d startleft-docs

```

--------------------------------

### StartLeft server on specific port

Source: https://iriusrisk.github.io/startleft/startleft-processors/diagram/drawio/Drawio-Quickstart

Starts the StartLeft server on a specified port using the -p flag. Example uses port 8080.

```bash
startleft server -p 8080

```

--------------------------------

### get function signature

Source: https://iriusrisk.github.io/startleft/startleft-processors/iac/tf/Terraform-additional-jmespath-functions

Signature of the custom JMESPath function get. It takes a dictionary array of components and a component type, returning a component dictionary with root key as the component name, including 'Type' and '_key' keys. Example usage: resource|get(@, 'aws_subnet').

```python
def _func_get(self, obj_arr, component_type)
```

--------------------------------

### get_starts_with function signature

Source: https://iriusrisk.github.io/startleft/startleft-processors/iac/tf/Terraform-additional-jmespath-functions

Signature of the custom JMESPath function get_starts_with. It is equivalent to get but filters components whose type starts with the given component_type.

```python
def _func_get_starts_with(self, obj_arr, component_type)
```

--------------------------------

### Get version via CLI: startleft --version

Source: https://iriusrisk.github.io/startleft/Versioning

Run this command in a terminal to display the installed StartLeft version. The output is the version string, e.g., '1.5.0'.

```bash
startleft --version

```

--------------------------------

### Download the Visio mapping file

Source: https://iriusrisk.github.io/startleft/Quickstart-Guide-for-Beginners

Downloads the IriusRisk Visio mapping file from the StartLeft repository's examples/visio folder.

```bash
wget https://raw.githubusercontent.com/iriusrisk/startleft/main/examples/visio/iriusrisk-visio-aws-mapping.yaml

```

--------------------------------

### Show general CLI help

Source: https://iriusrisk.github.io/startleft/Quickstart-Guide-for-Beginners

Displays general help for the StartLeft CLI, listing all available commands and options.

```bash
startleft --help

```

--------------------------------

### Terraform Example for Two Security Groups Dataflow

Source: https://iriusrisk.github.io/startleft/startleft-processors/iac/tf/Terraform-how-dataflow-mapping-works

Terraform configuration example that creates a VPC, two subnets, two security groups, ingress and egress security group rules, an ECS service, and a load balancer. This setup demonstrates the scenario where two security groups are between two connected resources, leading to dataflow mapping.

```hcl
resource "aws_vpc" "CustomVPC" {
  cidr_block  = "10.0.0.0/16"
}
resource "aws_subnet" "PrivateSubnet1" {
  vpc_id     = aws_vpc.CustomVPC.id
}
resource "aws_subnet" "PrivateSubnet2" {
  vpc_id     = aws_vpc.CustomVPC.id
}
resource "aws_security_group" "OutboundSecurityGroup" {
  vpc_id        = aws_vpc.CustomVPC.id
}
resource "aws_security_group" "ServiceLBSecurityGroup" {
  vpc_id        = aws_vpc.CustomVPC.id
}
resource "aws_security_group_rule" "OutboundSecurityGroupIngressfromServiceLBSecurityGroup" {
  type                      = "ingress"
  from_port                 = 80
  to_port                   = 80
  protocol                  = "tcp"
  security_group_id         = aws_security_group.OutboundSecurityGroup.id
  source_security_group_id  = aws_security_group.ServiceLBSecurityGroup.id
  description               = "Load balancer to target"
}
resource "aws_security_group_rule" "ServiceLBSecurityGroupEgresstoOutboundSecurityGroup" {
  type                      = "egress"
  from_port                 = 80
  to_port                   = 80
  protocol                  = "tcp"
  security_group_id         = aws_security_group.ServiceLBSecurityGroup.id
  source_security_group_id  = aws_security_group.OutboundSecurityGroup.id
  description               = "Load balancer to target"
}
resource "aws_ecs_service" "Service" {
  network_configuration {
    subnets = [aws_subnet.PrivateSubnet1.id, aws_subnet.PrivateSubnet2.id]
    security_groups = [aws_security_group.OutboundSecurityGroup.id]
  }
}

resource "aws_lb" "ServiceLB" {
  security_groups             = [aws_security_group.ServiceLBSecurityGroup.id]
  subnets                     = [aws_subnet.PrivateSubnet1.id, aws_subnet.PrivateSubnet2.id]
}

```

--------------------------------

### startleft

Source: https://iriusrisk.github.io/startleft/usage/Command-Line-Interface

Main CLI entry point. Running without arguments displays help with available commands and global options.

```APIDOC
## startleft

### Description
Main CLI entry point. Running without arguments displays help with available commands and global options.

### Method
CLI

### Endpoint
`startleft`

### Parameters
#### Global Options
- `-l, --log-level [CRIT|ERROR|WARN|INFO|DEBUG|NONE]` - Optional - Set the log level.
- `-v, --verbose / -nv, --no-verbose` - Optional - Makes logging more verbose.
- `--version` - Optional - Show the version and exit.
- `--help` - Optional - Show this message and exit.

### Commands
- `parse` - Parses source files into Open Threat Model
- `search` - Searches source files for the given query
- `server` - Launches the REST server to generate OTMs from requests
- `summary` - Generates a summary CSV file of the given source files
- `validate` - Validates a mapping or OTM file

### Request Example
```
$ startleft
```

### Response
#### Success Response
Displays usage information and exits.

#### Response Example
```
Usage: startleft [OPTIONS] COMMAND [ARGS]...

  Parse IaC and other files to the Open Threat Model format

Options:
  -l, --log-level [CRIT|ERROR|WARN|INFO|DEBUG|NONE]
                                  Set the log level.
  -v, --verbose / -nv, --no-verbose
                                  Makes logging more verbose.
  --version                       Show the version and exit.
  --help                          Show this message and exit.

Commands:
  parse     Parses source files into Open Threat Model
  search    Searches source files for the given query
  server    Launches the REST server to generate OTMs from requests
  summary   Generates a summary CSV file of the given source files
  validate  Validates a mapping or OTM file
```
```

--------------------------------

### startleft server --help output

Source: https://iriusrisk.github.io/startleft/usage/REST-API

Shows usage and options for the startleft server command, including the -p/--port option.

```text
startleft server --help
Usage: startleft server [OPTIONS]...

  Launches the REST server to generate OTMs from requests

Options:
  -p, --port INTEGER  StartLeft deployment port.
  --help              Show this message and exit.
```

--------------------------------

### Install libmagic on OSX

Source: https://iriusrisk.github.io/startleft/Quickstart-Guide-for-Beginners

Install libmagic on OSX using either Homebrew or MacPorts.

```bash
brew install libmagic
```

```bash
port install file
```

--------------------------------

### Run Visio summary by file path

Source: https://iriusrisk.github.io/startleft/startleft-processors/diagram/visio/Visio-Summary

Executes the summary against a unique Visio file using the specified default mapping file.

```bash
startleft summary \
--diagram-type VISIO \
--default-mapping-file examples/visio/iriusrisk-visio-aws-mapping.yaml \
examples/visio/aws-with-tz-and-vpc.vsdx

```

--------------------------------

### OTM Threat Instance and Mitigation Instance Mapping Example

Source: https://iriusrisk.github.io/startleft/startleft-processors/external-threat-model/mtmt/MTMT-Mapping

Example of an OTM threat instance with its mitigation instance, mapped to the corresponding OTM component. The threat and mitigation references use the IDs from the previous examples.

```json
{
  "threat": "30",
  "state": "AutoGenerated",
  "mitigations": [
    {
      "mitigation": "30",
      "state": "RECOMMENDED"
    }
  ]
}
```

--------------------------------

### StartLeft server startup log

Source: https://iriusrisk.github.io/startleft/integration/Quickstart-Guide-for-Integrations

Expected log output when the StartLeft service starts successfully.

```text
INFO:     Started server process [1]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:5000 (Press CTRL+C to quit)
```

--------------------------------

### Future Python script using slp_visio VisioProcessor

Source: https://iriusrisk.github.io/startleft/integration/Quickstart-Guide-for-Integrations

Shows a future example of using StartLeft as a Python library to convert a Visio file to OTM. The script imports VisioProcessor, creates an instance with project ID, name, source file, and mappings, then calls process(). This is not yet recommended due to potential breaking changes.

```python
from slp_visio import VisioProcessor

visio_processor = VisioProcessor(
    project_id='sample-project-id', 
    project_name='sample-project-name', 
    source=open('visio.vsdx', 'r'), 
    mappings=[open('mapping.yaml', 'r')])

otm = visio_processor.process()

```

--------------------------------

### Install python-magic-bin for Windows

Source: https://iriusrisk.github.io/startleft/Quickstart-Guide-for-Beginners

Install the python-magic-bin package to provide the required DLLs for libmagic on Windows.

```bash
pip install python-magic-bin
```

--------------------------------

### Run Visio summary by multiple file paths

Source: https://iriusrisk.github.io/startleft/startleft-processors/diagram/visio/Visio-Summary

Executes the summary against multiple Visio files using the specified default mapping file.

```bash
startleft summary \
--diagram-type VISIO \
--default-mapping-file examples/visio/iriusrisk-visio-aws-mapping.yaml \
examples/visio/aws-with-tz-and-vpc.vsdx examples/visio/visio-basic-example.vsdx

```

--------------------------------

### Install Graphviz with Homebrew on macOS

Source: https://iriusrisk.github.io/startleft/Troubleshooting

On macOS, ensure Graphviz is installed using Homebrew before attempting to build pygraphviz.

```shell
brew install graphviz
```

--------------------------------

### Install python3.x-dev development package

Source: https://iriusrisk.github.io/startleft/Troubleshooting

Install the development package for your Python version to resolve the Python.h header file error.

```shell
sudo apt install python3.x-dev
```
Tokens:
Raw