Skip to content

Contrast-Security-OSS/cargo-cats

BranchesTags

Repository files navigation

Cargo Cats 📦

Cargo Cats is a multi-language microservice application designed as a purposefully vulnerable demo application for security testing and education. It simulates a shipping/logistics platform with various intentional security vulnerabilities. All services are automatically instrumented using the Contrast Security Flex Agent via agent-operator for runtime application security monitoring.

A dedicated simulation console provides a centralized interface for controlling traffic patterns, including normal user behavior, attack simulations, and exploit scenarios. This allows you to generate realistic traffic and security events to demonstrate how different security tools detect and respond to threats.

The application includes other styles of monitoring with ModSecurity WAF running on the ingress pod for web application firewall protection, and Falco installed on each pod for OS based runtime security monitoring. All logs from these security tools are collected in a built-in OpenSearch instance with preconfigured dashboards for centralized monitoring and analysis.

flowchart TB
    User([👤 User / Attacker])

    subgraph K8S["Kubernetes Cluster"]
        direction TB

        Ingress["<b>nginx-ingress</b><br/>━━━━━━<br/>🛡️ <font color='#0066cc'>ModSecurity WAF</font>"]

        subgraph APP["Vulnerable Application"]
            direction TB
            FG["<b>frontgateservice</b><br/>Java<br/>━━━━━━━━━━━━━━<br/><font color='#c00'>⚠️ XSS · Log4Shell · BrokenAC<br/>HTTPOnly · Deserialization</font><br/>━━━━━━━━━━━━━━<br/>🛡️ <font color='#093'>Contrast</font> | <font color='#0066cc'>Falco</font>"]

            subgraph BE["Backends"]
                direction LR
                DS["<b>dataservice</b><br/>Java<br/>━━━━━━<br/><font color='#c00'>⚠️ SQLi · MD5</font><br/>━━━━━━<br/>🛡️ <font color='#093'>Contrast</font> | <font color='#0066cc'>Falco</font>"]
                WH["<b>webhookservice</b><br/>Python<br/>━━━━━━<br/><font color='#c00'>⚠️ SSRF · Cmd Inj</font><br/>━━━━━━<br/>🛡️ <font color='#093'>Contrast</font> | <font color='#0066cc'>Falco</font>"]
                IS["<b>imageservice</b><br/>.NET<br/>━━━━━━<br/><font color='#c00'>⚠️ Path Traversal</font><br/>━━━━━━<br/>🛡️ <font color='#093'>Contrast</font> | <font color='#0066cc'>Falco</font>"]
                LS["<b>labelservice</b><br/>Node.js<br/>━━━━━━<br/><font color='#c00'>⚠️ SSJS</font><br/>━━━━━━<br/>🛡️ <font color='#093'>Contrast</font> | <font color='#0066cc'>Falco</font>"]
                DC["<b>docservice</b><br/>Python<br/>━━━━━━<br/><font color='#c00'>⚠️ XXE</font><br/>━━━━━━<br/>🛡️ <font color='#093'>Contrast</font> | <font color='#0066cc'>Falco</font>"]
                RS["<b>reportservice</b><br/>Java<br/>━━━━━━<br/><font color='#c00'>⚠️ SSTI</font> · <font color='#555'>🤖 shadow AI</font><br/>━━━━━━<br/>🛡️ <font color='#093'>Contrast</font> | <font color='#0066cc'>Falco</font>"]
                AS["<b>aiservice</b><br/>Java<br/>━━━━━━<br/><font color='#555'>🤖 AI SDK demo</font><br/>━━━━━━<br/>🛡️ <font color='#093'>Contrast</font> | <font color='#0066cc'>Falco</font>"]
                OL[("</b>ollama</b><br/>local LLM")]
                DB[("<b>MySQL</b><br/>db + credit_cards")]
            end
        end

        subgraph SIM["Simulation Tools"]
            direction LR
            CU["<b>console-ui</b><br/>Python · Flask"]
            ZAP["<b>zapproxy</b><br/>OWASP ZAP"]
            CU -- "drives scans" --> ZAP
        end

        subgraph SUPP["Supporting Services"]
            direction TB
            EX["<b>exploit-server</b><br/><i>JNDI kit for Log4Shell</i>"]
            CDC["<b>contrastdatacollector</b><br/><i>pulls ADR from Contrast SaaS</i>"]
            OSN[("<b>opensearch-node</b><br/><i>logs + ADR store</i>")]
            OSD["<b>opensearch-dashboard</b><br/><i>logs UI</i>"]
            EX ~~~ CDC
            CDC ~~~ OSN
            OSN ~~~ OSD
        end
    end

    User --> Ingress
    Ingress --> FG
    Ingress --> CU
    Ingress ~~~ ZAP
    FG --> DS
    FG --> WH
    FG --> IS
    FG --> LS
    FG --> DC
    FG --> RS
    FG --> AS
    AS --> OL
    RS --> OL
    DS --> DB
    WH --> DB

    CU  -. "generates traffic + exploits" .-> Ingress
    ZAP -. "generates attacks" .-> Ingress

    ZAP ~~~ EX

    classDef vuln fill:#e8e8e8,stroke:#888,color:#000
    classDef sim  fill:#e6f3ff,stroke:#06c,color:#000
    classDef supp fill:#fff4d4,stroke:#c80,color:#000
    class FG,DS,WH,IS,LS,DC,RS,AS,OL,DB,Ingress vuln
    class CU,ZAP sim
    class EX,CDC,OSN,OSD supp
Loading

Architecture

Vulnerable Application Services

The core application consists of eight intentionally vulnerable microservices:

  • Frontgateservice (Java/Spring Boot) - Web frontend, authentication, and API gateway to other services
  • Dataservice (Java/Spring Boot) - Handles data operations and payment processing
  • Webhookservice (Python/Flask) - Handles webhook notifications
  • Imageservice (C#/.NET) - Manages photo uploads and file operations
  • Labelservice (Node.js) - Generates shipping labels and handles address processing
  • Docservice (Python/Flask) - DOCX document processor
  • Reportservice (Java/Tomcat) - Shipping report template engine with shadow AI: the OpenAI Java SDK is embedded directly inside the report rendering servlet, silently enriching reports with a logistics insight via Ollama. There is no AI-branded endpoint — Contrast detects the AI SDK usage from inside what appears to be a pure report rendering service.
  • AiService (Java/Spring Boot) - Dedicated AI service for the "Shipping Advisor" chatbot. Uses the OpenAI Java SDK pointed at a local Ollama instance, representing explicit/declared AI usage.

Simulation and Monitoring Tools

The deployment includes comprehensive security monitoring and traffic simulation capabilities:

  • Simulation Console - Traffic simulation and testing control center with links to all necessary tools
  • Exploit Server - Hosts the log4shell payload
  • Contrast Agent Operator - Runtime application security monitoring and instrumentation using the Contrast Flex agent for all services
  • ModSecurity WAF - Web application firewall protection on ingress pods
  • Falco - Runtime security monitoring for OS-level threats
  • OpenSearch - Centralized log collection and analysis with preconfigured dashboards

📋 Vulnerability Documentation

For detailed information about the security vulnerabilities present in this application, including exploitation steps and attack scenarios, see the Security Vulnerabilities Documentation.

This documentation covers:

  • Cross-Site Scripting (XSS)
  • SQL Injection
  • Log4Shell (CVE-2021-44228)
  • Server-Side Request Forgery (SSRF)
  • Command Injection
  • Path Traversal
  • XML External Entity (XXE) Injection
  • Server-Side Template Injection (SSTI) / RCE (CVE-2025-64087)
  • Server-Side JavaScript Injection (SSJS)
  • Untrusted Deserialization
  • Weak Password Storage (MD5 Hashing)
  • Missing Authentication
  • Insecure Session Management - HTTPonly missing

🤖 AI Observability Documentation

For a walkthrough of the two AI usage patterns (explicit chatbot in aiservice and shadow AI embedded in reportservice), see the AI Demo Documentation.

Both patterns can be toggled independently in values.yaml without rebuilding images:

ai:
  chatbotEnabled: true   # explicit chatbot in aiservice
  shadowEnabled: true    # shadow AI insight injection in reportservice

Prerequisites

Before you can deploy Cargo Cats, ensure you have the following installed:

  1. Docker Desktop (recommended) with Kubernetes enabled

    • Install Docker Desktop
    • Important: Go to Settings → Resources and allocate at least 12 GB of memory (14 GB recommended). The default 8 GB is not sufficient.
    • Go to Settings → Kubernetes → Enable Kubernetes
    • Important: Cargo Cats requires the kubeadm Kubernetes provider. Recent versions of Docker Desktop changed the default provider to kind, which is not supported.
      • In Settings → Kubernetes, set the provider to kubeadm before enabling Kubernetes
      • If you already have Kubernetes running with kind, switch to kubeadm and reset the cluster
    • Wait for Kubernetes to start (green indicator)

    Don't have Docker Desktop? You can set up a local Kubernetes cluster using k3s or Minikube instead. See the Alternative Cluster Setup Guide for instructions.

  2. Helm (Kubernetes package manager)

    # macOS with Homebrew
brew install helm

# Or download from: https://helm.sh/docs/intro/install/

  3. kubectl (usually comes with Docker Desktop)

Setup

  1. Clone the repository

    git clone <repository-url>
cd cargo-cats

  2. Configure environment variables

    cp env.example .env

    Edit the .env file and set the required values:

    CONTRAST__AGENT__TOKEN=your-contrast-agent-token
CONTRAST__UNIQ__NAME=your-unique-name

    Note: The CONTRAST__UNIQ__NAME value is prepended to each service's application name in Contrast, following the pattern {CONTRAST__UNIQ__NAME}-cargocats-{service} (e.g. bob-cargocats-frontgateservice). This keeps your application and server names unique in the Contrast UI and prevents conflicts with other deployments. Pick something that identifies you (your name, initials, etc).

    Optional: For advanced features, you can also set these additional environment variables:

    CONTRAST__API__KEY=your-api-key
CONTRAST__API__AUTHORIZATION=your-authorization-header

    Note: The optional CONTRAST__API__KEY and CONTRAST__API__AUTHORIZATION variables enable ADR data fetching into OpenSearch and ADR deletion functionality when deployed in certain environments. These are not required for basic operation.

Deployment

Once you have completed the setup, deploy the application with a single command:

make deploy

This command will:

  1. Validate your environment variables
  2. Build all Docker containers for the microservices
  3. Deploy the application using Helm
  4. Deploy the security monitoring tools (WAF, Falco, Contrast ADR)
  5. Deploy OpenSearch to aggregate WAF/EDR logs
  6. Deploy Simulation Console to simulate traffic and provide easy access to tools.

Accessing the Application

After deployment completes (may take a few minutes), you can access:

  • Vulnerable Application: http://app.localhost

    • Username: admin
    • Password: password123

  • Simulation Console: http://console.localhost

    • Centralized control center providing links to all necessary tools
    • Controls for simulating normal traffic patterns
    • Attack traffic simulation (non-exploitative testing)
    • Exploit traffic generation for security testing

  • OpenSearch Dashboard: http://opensearch.localhost

    • Username: admin
    • Password: Contrast@123!

Cleanup

To remove the application and all associated resources:

make uninstall

This will remove the Helm deployment and delete the contrast-agent-operator namespace.

Remember: This application is intentionally vulnerable and should only be used in secure, isolated environments for testing and educational purposes.

About

No description, website, or topics provided.

Resources

Readme
Activity
Custom properties

Stars

4 stars

Watchers

1 watching

Forks

14 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages