How the agent works

The Ghostpsy agent is a single static Go binary that runs on Linux. It collects system configuration data and sends it to the API for analysis.

Scan lifecycle

1. Collect — the agent reads system files, runs allowlisted commands, and builds a JSON payload
2. Preview — the user can inspect the payload before sending (dry-run mode)
3. Send — the payload is sent to POST /v1/ingest with a one-time bearer token
4. Analyze — the API validates the payload, runs WAN probes, and triggers AI analysis
5. Report — the structured report is persisted and displayed in the dashboard

What the agent reads

The agent only reads existing system state. It does not:

• Modify any file or configuration
• Install packages or services
• Open network connections (other than the API call)
• Run interactive commands
• Access user data, database contents, or application secrets

System commands

All commands are allowlisted — the agent only runs specific commands with known arguments. Examples:

Command	Purpose
uname -r	Kernel version
cat /etc/os-release	OS identification
ss -tlnp	Listening sockets
iptables -L -n	Firewall rules
apt-get -s dist-upgrade	Pending package updates (simulation only)
nginx -v	Nginx version
postgres -V	PostgreSQL version
docker info	Docker daemon configuration

Configuration files

The agent reads configuration files for detected services:

• /etc/ssh/sshd_config — SSH configuration (password auth, root login, key algorithms)
• /etc/nginx/nginx.conf — Nginx server configuration
• /etc/apache2/apache2.conf — Apache configuration
• /etc/postgresql/*/postgresql.conf — PostgreSQL settings
• /etc/mysql/my.cnf — MySQL/MariaDB settings
• Redis configuration — bind address, protected mode

The agent never reads secret files (private keys, passwords, .env files, database contents).

Payload structure

The collected data is organized into components:

components/
  core_system_and_kernel/     # OS, kernel, hostname, uptime, clock
  security_frameworks/        # SSH, firewall, SELinux/AppArmor
  software_packages/          # Installed services, versions, updates
  cryptography/               # TLS certificates, NTP sync
  network/                    # Listeners, public IP, DNS
  filesystem/                 # Disk usage, mount points
  container_and_cloud_native/ # Docker, Kubernetes workloads

The full schema is defined in api/ingest.v1.schema.json and validated at ingest time.

Privacy

• The agent shows the payload before sending (confirm with y)
• Dry-run mode (--dry-run) collects data without sending anything
• No credentials, secrets, or user data are collected
• The payload is sent over HTTPS to the Ghostpsy API only