Skip to content
This repository has been archived by the owner on May 30, 2023. It is now read-only.

Latest commit

 

History

History
189 lines (148 loc) · 8.99 KB

README.md

File metadata and controls

189 lines (148 loc) · 8.99 KB

Invadium

Invadium

GitHub Latest Release GitHub Workflow Status GitHub License

Invadium runs exploits against one or more target applications in an intuitive, reproducable, and well-defined manner. It focuses on bridging the gap between developers that write exploits and presenters that use them for demos or educational purposes.

  • Presenters can easily navigate to the web UI of Invadium, chose from a selection of exploits and demo their individual attack steps, all within Invadium.
  • Exploit developers define exploits by specifying a container image for it, environment variables for customization, and the individual commands that will be run at each step.

Of course, Invadium is not only built for exploits, you may solve similar problems, e.g., showcasing new users how a tool of yours can be used, getting a web UI for a set of commands that developers may regularly encounter, etc.

⚠️ This product is not officially supported by Dynatrace.

🎬 Can I see it in action?

Sure! Below you see a presenter navigating to Invadium, selecting the Nmap network scanner and running only the first step of it, a standard scan of the target address.

Invadium Demo

What you are seeing above is defined in a so-called exploit format. Below you see an excerpt of how this can look like for the Nmap exploit. The excerpt only shows one step, find the full file at ./exploits/config/nmap.yaml or start writing your own today!

id: nmap
name: Nmap
desc: |
  Nmap ("Network Mapper") is a free and open source utility
  for network discovery and security auditing.
image: ghcr.io/dynatrace-oss/invadium-nmap
env:
  - name: TARGET
    value: scanme.nmap.org
    desc: Target address to scan
steps:
  nmap_scan:
    name: Standard scan
    desc: Scans all reserved TCP ports on the target
    commands:
      - nmap -T$TIMING $OPTIONS $TARGET
    env:
      - name: TIMING
        value: 5
        desc: Timing template between 0 - 5 (higher is faster)
      - name: OPTIONS
        desc: Additional options for nmap

How does this work under the hood?

Invadium is split into a Next.js frontend and a Python backend, backed by FastAPI.

  1. Starting an exploit starts a new exploit container. If you run in docker mode, this spawns a new Docker container. If you run in kubernetes mode, a new pod is spawned in your namespace.
  2. When you execute individual steps, the backend will run docker exec and kubectl exec, respectively, and stream the logs into the frontend. One exploint container can run one or more steps.
  3. When you end your session, or after a certain timeout, the spawned containers or pods will be deleted again.
graph LR;
  subgraph Docker Host or Kubernetes Cluster
    frontend["Next.js<br/>Frontend"]
    backend["FastAPI<br/>Backend"]
    exploit1["fa:fa-dragon Exploit Container A"]
    exploit2["fa:fa-dragon Exploit Container B"]
    frontend --> backend;
    backend --> exploit1;
    backend --> exploit2;
  end

  exploit1 --> target
  exploit1 --> target
  exploit2 --> target

  subgraph Test System
    target["fa:fa-shopping-cart Target App"]
  end
Loading

🐳 Quick Start with Docker

You already have Docker and Compose installed? Awesome! Just run the following command. 1

docker-compose up --no-build -d

You should see the sqlmap and Nmap exploits that are read from ./exploits/config. Find the exploit format specification over here if you want to start writing your own!

1 This will pull images from GHCR.io - if you want to re-build the containers yourself, use --build instead.

⚓ Kubernetes Deployment

Invadium is ready for Kubernetes! Find detailed guides over here.

💻 Local Development

Planning to extend or adapt Invadium? This might be valuable for you:

⚙️ Configuration

Backend Directories

The backend expects exploit YAML files in the directory that you specified with the environment variable INVADIUM_CONFIG_PATH. This needs to be set when you start the Python backend. In our container images this is set to /config by default. You can mount your exploit YAML files there.

Backend Environment Variables

Variable Type Description Default
INVADIUM_CONFIG_PATH str Path where the exploit config YAML files are located not set
INVADIUM_API_PORT int Port where the backend API will listen 3001
INVADIUM_API_ROOT str Prefix that is appended to API routes and the docs 1 /api
INVADIUM_CORS_ORIGINS (optional) list[str] Origins that are allowed to call the backend 2 not set
INVADIUM_EXPLOIT_RUNTIME str Runtime to use for exploit containers (docker or kubernetes) docker
INVADIUM_EXPLOIT_TIMEOUT int Amount of seconds after an idle exploit container is deleted 900 (15min)
INVADIUM_DOCKER_NETWORK (optional) str Spawns docker containers in a certain --network 3 not set
INVADIUM_KUBERNETES_NAMESPACE str Kubernetes namespace where new exploit pods are spawned invadium
INVADIUM_KUBERNETES_POD_CPU_REQUESTS str CPU requests per exploit pod in Kubernetes 100m
INVADIUM_KUBERNETES_POD_CPU_LIMITS str CPU limits per exploit pod in Kubernetes 250m
INVADIUM_KUBERNETES_POD_MEMORY_REQUESTS str Memory requests per exploit pod in Kubernetes 250Mi
INVADIUM_KUBERNETES_POD_MEMORY_LIMITS str Memory limits per exploit pod in Kubernetes 500Mi

1 For example, when you set this to /api you can then fetch from localhost:3001/api/exploits. Also, the documentation will be available at this location, e.g. browse localhost:3001/api to see the Swagger docs. In our container images, this is set to /api by default to allow for prefix-routing. Locally, there is no prefix defined.

2 Put in the URL of the frontend if it has a different origin than the backend. For a local setup, you best set this to ["http://localhost:3000", "http://127.0.0.1:3000"].

3 For example, this can be set to host to spawn exploit containers in the same network as the Docker host. In some local setups, this can make it easier to reach target apps from the exploit containers.

4 Check the official docs to learn more about requests and limits.

Frontend Environment Variables

Variable Type Description Default
NEXT_BACKEND_API_URL str Absolute or relative URL to the backend API 1 not set

1 This URL must be reachable from the browser window of the user. If you supply a relative URL, the window.location.origin will be prepended.