README
¶
ProjectDiscovery Cloud Platform — Agent
What it does • Quick Start • Install • Configuration • Scaling
What it does
pd-agent lets you scan your own internal networks from the ProjectDiscovery Cloud Platform.
Install the agent on a machine inside the network you want to scan — a VM, a server, a workstation, a Kubernetes pod — and connect it to your PDCP team. From the cloud UI you can then launch scans against private IPs, internal hostnames, VPC ranges, or Kubernetes clusters, and the agent will run them locally and stream results back. Nothing in your network needs to be exposed publicly.
Nuclei, httpx, naabu, dnsx, and tlsx are all built into the agent — there's nothing else to install on the host.
Quick Start
-
Get credentials. Sign in at https://cloud.projectdiscovery.io, copy your API key and team ID.
-
Run the agent on the machine that has access to the network you want to scan:
docker run -d --name pd-agent \ --network host --cap-add NET_RAW --cap-add NET_ADMIN \ -e PDCP_API_KEY=your-api-key \ -e PDCP_TEAM_ID=your-team-id \ ghcr.io/projectdiscovery/pd-agent:latest \ -agent-network prod-vpc -
Verify. Open the cloud UI's Agents tab — the agent appears within a few seconds with its discovered subnets.
-
Scan. Launch a scan from the UI and route it to your agent's network (
prod-vpcabove). The agent runs it locally and streams results back.
Other install paths (Kubernetes, native binary, systemd, launchd, Windows service) → docs/install.md.
What you can do with it
- Reach private targets the cloud platform can't see directly —
10.0.0.0/8,192.168.0.0/16, internal DNS, VPN-only services. - Scan a Kubernetes cluster from inside. The agent auto-discovers node IPs, pod CIDRs, and service CIDRs and reports them to the platform.
- Route scans to specific sites by assigning each agent a network name (
-agent-network) — e.g. one or more agents per data centre, region, or VPC. - Run everything PDCP can run in the cloud, against internal assets — vulnerability scans (nuclei), port discovery (naabu), HTTP probing (httpx), DNS enumeration (dnsx), TLS inspection (tlsx).
Documentation
| Topic | When to read |
|---|---|
| docs/install.md | First-time install on Linux, macOS, Windows, Docker, or Kubernetes. |
| docs/configuration.md | Every env var and CLI flag the agent accepts, and what they control. |
| docs/scaling.md | When to add more agents and which metric to drive autoscaling from. |
License
Distributed under the MIT License. Built with ❤️ by ProjectDiscovery.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
pd-agent
command
|
|
|
agentdb
Package agentdb persists agent info, structured logs, and resource metrics in a local SQLite database so they survive restarts and can be uploaded for offline investigation.
|
Package agentdb persists agent info, structured logs, and resource metrics in a local SQLite database so they survive restarts and can be uploaded for offline investigation. |
|
envconfig
Package envconfig owns every environment variable the agent reads.
|
Package envconfig owns every environment variable the agent reads. |
|
path
Package path is useful for managing PATH as part of the Environment in the Windows HKey Local User registry.
|
Package path is useful for managing PATH as part of the Environment in the Windows HKey Local User registry. |
|
prereq
Package prereq runs pd-agent's startup preflight: warm up the embedded headless browser and warn on Windows if Defender exclusions aren't set.
|
Package prereq runs pd-agent's startup preflight: warm up the embedded headless browser and warn on Windows if Defender exclusions aren't set. |
|
runtools
Package runtools embeds ProjectDiscovery scanners (tlsx, dnsx, httpx, naabu, nuclei) as Go SDK calls.
|
Package runtools embeds ProjectDiscovery scanners (tlsx, dnsx, httpx, naabu, nuclei) as Go SDK calls. |
|
selfupdate
Package selfupdate downloads a new pd-agent binary from GitHub releases and replaces the running binary via rename + syscall.Exec.
|
Package selfupdate downloads a new pd-agent binary from GitHub releases and replaces the running binary via rename + syscall.Exec. |