Skip to content

Getting Started with ThreatForest

Welcome to ThreatForest! This guide will help you get up and running with AI-powered threat modeling in minutes.

Installation Steps

Step 1: Install ThreatForest

# Install uv if you don't have it
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone and run — uv handles the environment automatically
git clone https://github.com/aws-samples/sample-agentic-attack-tree-generator.git
cd sample-agentic-attack-tree-generator
uv run threatforest

# Install pipx if you don't have it
python3 -m pip install --user pipx
python3 -m pipx ensurepath

# Install ThreatForest
git clone https://github.com/aws-samples/sample-agentic-attack-tree-generator.git
cd sample-agentic-attack-tree-generator
pipx install .

# Run ThreatForest
threatforest

# Clone repository
git clone https://github.com/aws-samples/sample-agentic-attack-tree-generator.git
cd sample-agentic-attack-tree-generator

# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install
pip install .

# Run ThreatForest
threatforest

Step 2: Configure your LLM provider

AWS Bedrock recommended

AWS Bedrock is fully tested and supported. Other providers (Anthropic, OpenAI, Gemini, Ollama, SageMaker) are experimental.

Configure an AWS profile with IAM permissions for:

  • bedrock:InvokeModel
  • bedrock:InvokeModelWithResponseStream
aws configure --profile your-profile-name
aws bedrock list-foundation-models --region us-east-1 --profile your-profile-name

Set your API key for Anthropic, OpenAI, or Gemini — or point to a local Ollama instance. See Configuration for all provider options.

Run the configuration wizard (or use the Configure page in the web console):

threatforest config init

Step 3: Prepare Your Project

At minimum, ThreatForest needs one of the following in your project directory:

  • ThreatComposer file (.tc.json) - Recommended, created at threat-composer
  • README.md - Application description and architecture overview
  • Architecture diagrams - PNG, PDF, Mermaid, or other diagram formats

Quick Setup:

your-project/
├── README.md              # Describes your application
└── MyApp.tc.json         # Your threat model

Learn More

See the User Guide → Preparing Your Project for complete details on supported formats and best practices.

Step 4: Run Your First Analysis

threatforest

Opens the web console at http://localhost:8000 automatically. From there:

  1. Go to Applications and select your project
  2. Click New Run to start an analysis
  3. Watch real-time progress on the Run page
  4. View results in the interactive dashboard when complete
threatforest --tui

Launches the interactive terminal wizard. Follow the prompts to select a project path and start the analysis.

Next Steps

Now that you have ThreatForest installed, explore these guides:

  • 🚀 Running ThreatForest

    Web console, terminal mode, and CLI options

    → Learn More

  • 📁 Preparing Your Project

    Optimize inputs for better threat analysis results

    → Prepare Project

  • 📊 Understanding Results

    Explore outputs and use the interactive dashboard

    → Explore Results

  • ⚙️ Configuration

    LLM providers, config file, and advanced settings

    → Configure

Need Help?

Having issues? Check the FAQ Troubleshooting section for common problems and solutions.