Skip to content

Latest commit

 

History

History
430 lines (294 loc) · 10.5 KB

DEVELOPMENT.md

File metadata and controls

430 lines (294 loc) · 10.5 KB

Threat Composer Development Guide

This guide covers development setup, architecture, and contribution guidelines for the Threat Composer project.

Repository Overview

This monorepo hosts multiple packages that make up the Threat Composer ecosystem:

  • threat-composer: Core UI components library
  • threat-composer-app: Web application (SPA)
  • threat-composer-app-browser-extension: Browser extension for Chrome/Firefox
  • threat-composer-infra: AWS CDK infrastructure code
  • threat-composer-ai: AI-powered CLI and MCP server for automated threat modeling

The repository is defined and maintained using projen and aws-prototyping-sdk.

Repository Structure

Project Path Description Tech Stack
threat-composer packages/threat-composer UI components for threat-composer React, CloudScape design system
threat-composer-app packages/threat-composer-app threat-composer Single Page App (SPA) bootstrapped by create-react-app React
threat-composer-infra packages/threat-composer-infra threat-composer Infrastructure CDK App aws-prototyping-sdk constructs
threat-composer-app-browser-extension packages/threat-composer-app-browser-extension threat-composer browser extension wxt, React
threat-composer-ai packages/threat-composer-ai AI-powered CLI and MCP server Python, Strands, FastMCP

Prerequisites

Required Tools

Optional Tools (for specific packages)

  • AWS CLI (version 2 or higher) - For infrastructure deployment
  • AWS CDK v2 - Install via npm install -g aws-cdk
  • Python 3.10+ - For threat-composer-ai package
  • UV - Python package manager for threat-composer-ai

Getting Started

Clone the Repository

git clone https://github.com/awslabs/threat-composer.git
cd threat-composer

Install Dependencies

pdk install --frozen-lockfile

This will install all dependencies for all packages in the monorepo.

Build All Projects

pdk build

This builds all packages in the correct dependency order.

Development Workflows

Working with UI Components (threat-composer)

The threat-composer package contains the core UI components. The recommended development environment is Storybook.

Run Storybook

pdk run storybook

Open http://localhost:6006 to view it in the browser. The page will reload if you make edits.

This is the recommended development environment for UI component work.

Run Tests

cd packages/threat-composer
yarn test

Working with the Web App (threat-composer-app)

Start Development Server

pdk run dev

This starts the web application in development mode. Open http://localhost:3000 to view it in the browser.

Build for Production

cd packages/threat-composer-app
yarn build

The build artifacts will be in the build/ directory.

Working with the Browser Extension

See the Browser Extension README for detailed instructions.

Quick start:

cd packages/threat-composer-app-browser-extension

# Chrome development
yarn run dev

# Firefox development
yarn run dev:firefox

Working with Infrastructure (threat-composer-infra)

Deploy to AWS

# Deploy dev environment
./scripts/deployDev.sh

# Deploy with CI/CD pipeline
./scripts/deployAll.sh

CDK Commands

cd packages/threat-composer-infra

# Synthesize CloudFormation template
cdk synth

# Deploy stack
cdk deploy

# Destroy stack
cdk destroy

Working with AI Package (threat-composer-ai)

cd packages/threat-composer-ai

# Install dependencies
uv sync

# Run CLI
uv run threat-composer-ai-cli /path/to/codebase

# Run MCP server
uv run threat-composer-ai-mcp

# Run tests
uv run pytest

Project Commands

Monorepo Commands (from root)

# Install all dependencies
pdk install --frozen-lockfile

# Build all packages
pdk build

# Run Storybook
pdk run storybook

# Start web app dev server
pdk run dev

# Run all tests
pdk test

# Lint all packages
pdk run lint

# Format code
pdk run format

Package-Specific Commands

Navigate to the package directory and use yarn/npm commands:

cd packages/threat-composer

# Run tests
yarn test

# Build package
yarn build

# Lint
yarn lint

Code Organization

UI Components (packages/threat-composer/src/)

src/
├── components/          # React components
│   ├── application/     # Application info components
│   ├── architecture/    # Architecture components
│   ├── assumptions/     # Assumptions components
│   ├── threats/         # Threat components
│   └── mitigations/     # Mitigation components
├── contexts/            # React contexts
├── hooks/               # Custom React hooks
├── utils/               # Utility functions
├── data/                # Reference data
│   ├── workspaceExamples/
│   ├── threatPacks/
│   └── mitigationPacks/
└── styles/              # Global styles

Web App (packages/threat-composer-app/src/)

src/
├── components/          # App-specific components
├── containers/          # Container components
├── routes/              # Route definitions
├── hooks/               # App-specific hooks
└── utils/               # App utilities

Infrastructure (packages/threat-composer-infra/src/)

src/
├── application-stack.ts # Application CloudFormation stack
├── application-stage.ts # Application stage
├── pipeline-stack.ts    # CI/CD pipeline stack
└── pipeline.ts          # Pipeline definition

Testing

Unit Tests

# Run all tests
pdk test

# Run tests for specific package
cd packages/threat-composer
yarn test

# Run tests in watch mode
yarn test --watch

# Run tests with coverage
yarn test --coverage

Code Quality

Linting

# Lint all packages
pdk run eslint

Formatting

The project uses Prettier for code formatting:

# Format all code
pdk run format

Type Checking

# Type check all packages
pdk run type-check

# Type check specific package
cd packages/threat-composer
yarn type-check

Building for Production

Build All Packages

pdk build

Build Specific Package

cd packages/threat-composer
yarn build

Build Browser Extension

cd packages/threat-composer-app-browser-extension

# Build for Chrome
yarn build

# Build for Firefox
yarn build:firefox

# Create distribution ZIP
yarn run zip
yarn run zip:firefox

Deployment

Deploy Web Application

See Web App Documentation for detailed deployment instructions.

Quick deploy:

# Deploy dev environment
./scripts/deployDev.sh

# Deploy with CI/CD
./scripts/deployAll.sh

Contributing

Contribution Workflow

  1. Fork the repository
  2. Create a feature branch: git checkout -b feature/my-feature
  3. Make your changes
  4. Run tests: pdk test
  5. Run linting: pdk run lint
  6. Commit your changes: git commit -m "Add my feature"
  7. Push to your fork: git push origin feature/my-feature
  8. Create a Pull Request

Commit Message Guidelines

Follow conventional commit format:

type(scope): subject

body

footer

Types:

  • feat: New feature
  • fix: Bug fix
  • docs: Documentation changes
  • style: Code style changes (formatting, etc.)
  • refactor: Code refactoring
  • test: Test changes
  • chore: Build process or auxiliary tool changes

Code Review Process

  1. All changes require a pull request
  2. At least one approval required
  3. All CI checks must pass
  4. Code must follow project style guidelines

Troubleshooting

Common Issues

Dependency Installation Failures

git clean -fXd
pdk install --frozen-lockfile

Getting Help

  • Check existing GitHub Issues
  • Review Discussions
  • Read package-specific READMEs
  • Consult documentation in docs/ directory

Additional Resources

Documentation

License

This project is licensed under the Apache-2.0 License. See the LICENSE file for details.

Support

For bugs, issues, and feature requests, please use GitHub Issues.

For general questions and discussions, use GitHub Discussions.