pd-agent

ProjectDiscovery Cloud - Agent

PD Agent • Installation • Quick Start • System Installation • Join Discord

pd-agent is an agent for ProjectDiscovery Cloud Platform that executes internal discovery and scans remotely. It connects to the PDCP platform, receives scan configurations, executes them locally using ProjectDiscovery tools, and uploads results back to the cloud platform.

Features

Remote Execution: Connect to PDCP platform and execute scans remotely.
Workload Distribution: Support workload distribution acrsso multiple agents when available
Agent Tagging: Organize agents with tags and networks for targeted execution.

Installation

Go Install

go install github.com/projectdiscovery/pd-agent/cmd/pd-agent@latest

Docker

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 \
  projectdiscovery/pd-agent:latest \
  -agent-tags production

Network Discovery

The agent automatically discovers local network subnets and reports them to the platform. For Docker/K8s deployments, use --network host and network capabilities to enable this feature.

Environment Variables

Variable	Required	Default	Description
`PDCP_API_KEY`	Yes	-	API key for authentication
`PDCP_TEAM_ID`	Yes	-	Team identifier
`PDCP_AGENT_NETWORKS`	No	-	Comma-separated network identifiers
`PDCP_AGENT_TAGS`	No	-	Comma-separated agent tags
`PDCP_AGENT_NAME`	No	Hostname	Agent display name

Usage

# Basic usage
pd-agent -agent-networks internal

Configuration

The agent uses environment variables or command-line flags for configuration. See the Environment Variables table above for all available options.

Troubleshooting

Common Issues

Agent not connecting:

Verify PDCP_API_KEY and PDCP_TEAM_ID are correct
Check network connectivity to PDCP_API_SERVER
Ensure proxy settings are correct if using a proxy

Scans not executing:

Check agent tags match scan configuration tags
Verify agent ID is correct
Check verbose logs for error messages
Ensure output directory is writable

Permission errors:

Verify the user running the agent has write permissions to output directory
On Linux, check SELinux/AppArmor policies
On Windows, ensure service account has necessary permissions

Log Locations

Linux (systemd): journalctl -u pd-agent -f
macOS (launchd): ~/.pd-agent/logs/stdout.log and stderr.log
Windows: Event Viewer → Windows Logs → Application
Docker: docker logs pd-agent -f
Kubernetes: kubectl logs -l app=pd-agent -f

Enable Verbose Logging

Add -verbose flag or set environment variable:

export PDCP_VERBOSE=true
# or
PDCP_VERBOSE=1 pd-agent ...

Best Practices

Agent Tagging: Use descriptive tags to organize agents (e.g., production, staging, scanner-1)
Network Segmentation: Use -agent-networks to assign agents to specific networks
Resource Management: Monitor agent resource usage and adjust accordingly
Security: Always run agents with low privileges, never as root/Administrator
Monitoring: Set up monitoring and alerting for agent health
Output Management: Regularly clean up output directories to prevent disk space issues
Agent IDs: Use unique, descriptive agent IDs for easy identification

Advanced Configuration

Custom Proxy Configuration

Configure a custom proxy for agent communication:

export PROXY_URL=http://proxy.example.com:8080
pd-agent -verbose

Agent Grouping

Use tags and networks to group agents:

# Production agents
pd-agent -agent-tags production,us-east -agent-networks prod-network

# Staging agents
pd-agent -agent-tags staging,us-west -agent-networks staging-network