ThreatMapper: runtime threat management and attack path enumeration for cloud native

The gap ThreatMapper fills between build-time scanning and production reality

Most container scanning happens before deployment. An image is built, a scanner runs over its layers, and the pipeline fails or passes. That tells you what was in the image at build time. It says nothing about what is running three weeks later, what secrets got mounted into the pod, or whether the host kernel settings drifted away from a benchmark.

ThreatMapper targets that second window. The README describes it as hunting for threats in production platforms and ranking them by risk-of-exploit, uncovering vulnerable software components, exposed secrets and deviations from good security practice. The intended audience is the team that already has shift-left scanning in the pipeline and now needs security observability for workloads across cloud, Kubernetes, serverless (Fargate) and on-prem.

The ranking is the part that distinguishes it from a scanner that prints a list. ThreatGraph is the visualization layer where findings are ordered by how exposed they are, so the output is a prioritization rather than a report. Whether that ranking matches your own risk model is a question the README does not answer; it points at the product documentation and a live demo sandbox instead.

Console, sensors and cloud scanners: how the pieces talk

ThreatMapper is two halves. The Management Console is a container application deployed on a single Docker host or in a Kubernetes cluster. Everything else reports to it. The repository layout reflects that split: deepfence_server, deepfence_worker, deepfence_frontend, deepfence_postgres, deepfence_redis, deepfence_kafka and deepfence_neo4j are the console's own services, while deepfence_agent holds the sensor and its plugins.

The data flow has two entry points. Agentless Cloud Scanner tasks query cloud provider APIs to gather configuration and compare it against compliance benchmarks; the README says these are deployed with a Terraform module, with AWS, Azure and GCP expert configurations documented separately. Agent-based Sensor Agents are installed on production or development platforms, report to the console, describe the services they discover, send telemetry and generate manifests of software dependencies.

The Makefile shows the plugin boundary underneath the agent: SecretScanner, YaraHunter for malware, package-scanner, compliance and cloud-scanner are separate directories under deepfence_agent/plugins. That matters operationally, because a sensor is not one monolithic binary but a set of scanners whose findings the console correlates. The graph database is Neo4j, which is consistent with the attack path enumeration framing: paths between workloads are a graph query, not a table scan.

Installing the console and running your first sensor

The README gives an explicit Docker path for the console. It downloads the compose file from the release-2.5 branch and starts it detached. The console is deployed first, before any sensor or cloud scanner exists.

wget https://github.com/deepfence/ThreatMapper/raw/release-2.5/deployment-scripts/docker-compose.yml
docker-compose -f docker-compose.yml up --detach

After the containers come up, the README directs you to register an admin account and obtain an API key. That key is what sensors authenticate with, so the console must be reachable before the next step.

For a Docker host, the README's sensor command is a single privileged container. Note the three environment variables you must fill in: MGMT_CONSOLE_URL, MGMT_CONSOLE_PORT (443 in the example) and DEEPFENCE_KEY.

docker run -dit \
    --cpus=".2" \
    --name=deepfence-agent \
    --restart on-failure \
    --pid=host \
    --net=host \
    --privileged=true \
    -v /sys/kernel/debug:/sys/kernel/debug:rw \
    -v /var/run/docker.sock:/var/run/docker.sock \
    -v /:/fenced/mnt/host/:ro \
    -e MGMT_CONSOLE_URL="---CONSOLE-IP---" \
    -e MGMT_CONSOLE_PORT="443" \
    -e DEEPFENCE_KEY="---DEEPFENCE-API-KEY---" \
    quay.io/deepfenceio/deepfence_agent_ce:2.5.8

On Kubernetes the sensor goes in as a daemonset via a helm chart, and the README lists ECS, Fargate and bare-metal or VM hosts as the other supported targets. Once a sensor registers, it should appear in the console and begin reporting discovered services and dependency manifests; that is the signal the key and console URL are correct.

The privileged sensor is the real adoption constraint

Look again at that Docker command. The agent runs with --privileged=true, --pid=host, --net=host, mounts the Docker socket, mounts the host root read-only at /fenced/mnt/host/, and mounts /sys/kernel/debug read-write. Those flags are not incidental. Deep inspection of a host and its containers requires that level of access, and the README does not offer a reduced-privilege mode.

For a lot of organisations that is the whole decision. A container with the Docker socket mounted can start containers; one with the host PID namespace can see and signal host processes. If your security policy forbids privileged workloads in production namespaces, ThreatMapper's agent-based path is closed to you regardless of how good the findings are. The agentless Cloud Scanner does not carry that cost, but it only sees cloud provider configuration, not what is running inside your pods.

There is a second constraint that the README states only in passing: the console is itself a multi-service stack (Postgres, Redis, Kafka, Neo4j, a server, a worker and a frontend). That is a real footprint to run, patch and back up, and it means the console host becomes part of your security-critical infrastructure. The README does not document a rollback procedure for a failed console upgrade, nor a supported downgrade path.

How ThreatMapper differs from Trivy and other pipeline scanners

The obvious alternative for many teams is Trivy, which is the scanner most people already have in a pipeline. The difference is not detection quality; it is where the tool sits and what it knows.

Trivy runs as a command, typically against an image or a filesystem, and exits with a result. There is no server, no persistent inventory of what is running, and no graph of which workload can reach which other workload. ThreatMapper inverts that: the console is the persistent thing, and sensors and cloud scanners feed it continuously. It keeps monitoring running applications against emerging vulnerabilities, which is a posture a one-shot CI scan cannot hold.

The trade is operational weight. Trivy is a binary you can run anywhere in seconds. ThreatMapper is a stack plus agents with host-level privileges. If your need is to fail a build on a critical CVE, ThreatMapper is the wrong shape of tool. If your need is to know, next Tuesday, which of your running services is exploitable from the internet, that is the question it is built to answer. The README also notes ThreatMapper carries on existing shift-left practices rather than replacing them, which is the honest framing.

Licence, maintenance and what an upgrade actually costs

ThreatMapper is Apache-2.0, with the LICENSE file at the repository root. That permits commercial use and modification, and it is a permissive licence rather than a copyleft one, so embedding the console or sensors in a commercial offering does not by itself trigger source-disclosure obligations. This is a description of the licence text, not legal advice; the terms-of-use.txt file at the root is worth reading alongside it, and your own counsel should review anything you redistribute.

Maintenance is active but not fast-moving. The repository is not archived, and the last push was on 2026-06-01. The recent release history shows v2.5.6 and v2.5.7 in April 2025, then v2.5.8 on 2026-03-07, so roughly a year passed between the v2.5.7 and v2.5.8 tags. Plan upgrade windows around that cadence rather than assuming monthly drops.

Upgrade cost is dominated by version alignment. The README's sensor image is tagged 2.5.8 and the Makefile sets VERSION to v2.5.8, so the console and the agents are expected to move together. The README also notes that quay.io/deepfenceio/deepfence_agent_ce:2.5.8-multiarch is supported on amd64 and arm64/v8, which matters if your fleet is mixed. Because sensor deployment is per-platform (helm chart, task definition, sidecar, Docker container), a console upgrade means touching every one of those deployment mechanisms. The README does not describe a compatibility matrix for running a newer console against older agents.

Editorial conclusion

Adopt ThreatMapper if you run Kubernetes, Docker, ECS, Fargate or Linux hosts and want vulnerability, secret and compliance findings ranked by exploit risk rather than dumped as a flat list. Do not adopt it if you cannot grant sensor containers privileged host access, or if you only need a build-time image scan that runs inside CI. Before committing, verify three things: that the console version you deploy matches the sensor image tag you plan to run, that your Terraform workflow can apply the cloud scanner module for each provider you care about, and that the management console's own attack surface is acceptable on your network. The README's own deployment path is the docker-compose file in deployment-scripts, so start there and confirm the console answers on port 443 before installing a single sensor.

Frequently asked questions

Official sources

1. deepfence/ThreatMapper on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases