Velociraptor Guide: Endpoint Collection, Hunting and Incident Response at Scale

During an incident, the slowest part of the response is often getting the same evidence from hundreds or thousands of endpoints, quickly and in a form analysts can query. Velociraptor is an open-source endpoint visibility and collection tool that solves this with a central server, a lightweight client and a query language called VQL. This guide explains its architecture, the defender use cases that justify it, how to deploy and lock it down, and how it compares with other collection approaches. Because Velociraptor is, by design, a remote execution capability across your estate, a large part of the guide covers securing the server itself, including its certificates and API keys. It is written for incident responders, DFIR leads and the platform teams who run the server, and it covers defensive use only, based on the project's own documentation.

Key takeaways

• One server, many clients, one language. Clients keep a persistent connection to the server and run VQL artifacts on request, so a question asked once can be answered across the whole fleet.
• Hunts expire, they do not finish. A hunt keeps scheduling on newly seen matching clients until its expiry (one week by default).
• Offline collectors cover the hosts you cannot enrol. A preconfigured binary collects artifacts into an encrypted container that you import back into the server later.
• The server is a crown jewel. Anyone with admin-equivalent permissions, the CA private key or a powerful API key can run code on every enrolled endpoint. Treat those credentials as high-value non-human identities.
• Open source under AGPL, maintained with Rapid7. The repository is licensed under the GNU Affero General Public License v3, and Rapid7 acquired the project in April 2021.

What the tool does

Velociraptor collects host-based state using Velociraptor Query Language (VQL) queries. Its documentation describes three main components and two supporting capabilities.

• Server: runs on premises or in the cloud and is fully supported only on Linux. Investigators use its web GUI to task clients, collect artifacts and run hunts. It also exposes a gRPC API for automation. By default the frontend that clients connect to listens on port 8000 and the GUI on port 8889. Data is held in ordinary files (the FileBaseDataStore), with no external database.
• Client: the same binary installed as a service (for example from an MSI on Windows). Each client holds a persistent connection to the server and waits for work, so collections start within seconds rather than at the next check-in.
• VQL: a SQL-like language with SELECT ... FROM plugin() WHERE structure, no JOIN, and LET for variables (a plain = stores a lazy query, <= materialises it). Plugins return rows; functions return single values. A trivial example is SELECT OS FROM info().
• Artifacts: YAML files that package VQL with a name (such as Generic.Client.Info), description, type (CLIENT or SERVER, plus event types for monitoring), parameters, one or more sources with an optional precondition, and optional external tools. More than 400 artifacts are built into the binary, and the community Artifact Exchange adds more.
• Offline collector: a standard Velociraptor binary with a configuration and chosen artifacts embedded. Run without arguments, it collects, writes a container and optionally uploads it.

The project was developed by Mike Cohen, previously of Google's GRR and Rekall work, with community contributors. Rapid7 announced on 21 April 2021 that it had acquired Velociraptor and would keep it free and open source, while also using the technology in its own detection and response offerings. The repository LICENSE file is the GNU Affero General Public License version 3.

Defender use cases

• Fleet-wide triage: run a targeted artifact as a hunt to find which hosts show an indicator, such as a process name, a scheduled task or a mutex (Windows.Detection.Mutants), then collect deeper evidence only from those hosts. See the Threat Hunting Guide.
• Evidence collection at scale: pull Windows triage files remotely. The Windows.KapeFiles.Targets artifact reuses the community KapeFiles target definitions (for example the KapeTriage set), so teams that know KAPE can collect the same files without touching each host. What those files mean is covered in the Windows Forensic Artefacts Guide.
• Continuous monitoring: client event artifacts stream events (for example process creation or event log entries) to the server, giving responders a lightweight sensor where EDR coverage is thin. See the EDR Guide.
• Machine credential discovery: custom artifacts can look for cloud credential files, private keys and tokens left on hosts during an incident, which is often the fastest way to scope what an intruder could reuse. Feed findings into rotation. See the API Key Management Guide.

Choosing the collection mode

Small organisations without a standing DFIR team often get the most value from a prepared offline collector and a server kept ready but locked down until needed. Large organisations with an internal incident response function usually run clients permanently, because standing coverage removes deployment from the critical path of every incident.

Deployment and safe use

The documented path is: plan the deployment, generate a server configuration, build and install a server package, authorise users to the GUI, then build and deploy client packages. A phased approach keeps the risk proportionate.

1. Design the trust model first. Decide who may hold admin-equivalent permissions, which identity provider will authenticate users, where the CA key will live offline and how the GUI will be reached.
2. Build the server. Run it as a dedicated low-privilege service account on Linux, keep the configuration file writable only by root, place the GUI behind GUI.allowed_cidr or an SSH tunnel, and keep the API on 127.0.0.1 unless something external needs it. Upgrade to the current release: the documentation advised 0.77.3 at the time of writing to address CVEs in the 0.77.2 advisory.
3. Configure authentication. Avoid the Basic authenticator in production: the documentation notes its SHA-256 password hashing is weak and that any admin can reset any user's password across orgs. Use OIDC, OAuth2 or SAML with SSO and two-factor authentication enforced at the identity provider. See the Phishing-Resistant MFA Guide.
4. Remove the CA private key. Strip the CA.private_key section from the running configuration and keep a full copy offline, used only to issue API keys and roll server certificates (roughly yearly).
5. Pilot ring. Enrol a small group of hosts. Test every artifact you plan to hunt with on one or two endpoints first, as the documentation recommends; new hunts start Paused, which gives a natural review point.
6. Broad rollout. Deploy the client through software distribution, using labels to group hosts for targeting.
7. Return to lockdown between incidents. Set lockdown: true in the server configuration when no active response is under way. This denies ARTIFACT_WRITER, SERVER_ARTIFACT_WRITER, EXECVE, SERVER_ADMIN, FILESYSTEM_WRITE, FILESYSTEM_READ and MACHINE_STATE until an administrator with access to the host lifts it.

Rollback: clients are removed through the same software distribution channel used to install them. To stop new enrolments immediately, set Frontend.resources.enrollments_per_second to -1 and restart. If the server or its keys are compromised, treat it as an incident in its own right: rotate the CA, reissue client and API certificates, and rebuild the server.

Permissions and the identities behind them

Stick to built-in roles and grant the minimum: reader, analyst or investigator suit most users and API clients. The documentation treats ARTIFACT_WRITER, SERVER_ARTIFACT_WRITER, EXECVE, FILESYSTEM_WRITE and SERVER_ADMIN as admin-equivalent. Artifacts that can run arbitrary code, such as Windows.System.PowerShell, declare required_permissions (EXECVE). Prefer curated wrapper artifacts with fixed commands over granting EXECVE broadly. One point is easy to miss: client-side VQL runs without ACL checks, so reviewing artifacts before they are scheduled is the real control on endpoints, not the user's role.

API clients are non-human identities with certificates that last a year. Every API client needs the api role plus only the roles its job requires, private keys used interactively should be passphrase-encrypted, unused accounts should be deleted with user_delete(), and a compromised key is revoked with acl grant --role "". Track expiry and reissue before the one-year mark. If you enable mTLS, issue the shared client certificate with no roles. See the Machine Identity, PKI and Certificate Lifecycle Guide and the Privileged Access Management Guide.

Data handling

• Sensitivity: collections can contain browser history, credentials and personal data. Apply retention rules and access control to the datastore as you would to any evidence store.
• Offline collector encryption: use X.509 encryption, where a random password is encrypted to the server certificate and decrypted automatically on import. A fixed embedded password can be extracted by anyone with the binary, and unencrypted output is only for labs.
• Provenance: record which artifact, version and parameters produced each collection, and when. Evidence process is covered in the Evidence Handling and Chain of Custody Guide.

Detection and hardening value

Velociraptor gives defenders reach, and the same reach appeals to attackers. Sophos Counter Threat Unit reported an August 2025 intrusion in which the attacker used msiexec to install Velociraptor from a Cloudflare Workers staging domain, pointed it at attacker infrastructure and then used it to set up a Visual Studio Code tunnel. Sophos assessed the activity as a likely ransomware precursor.

On the hardening side, VQL restrictions narrow what a compromised account can do: security.denied_plugins can block execve, allowlists (security.allowed_plugins, security.allowed_functions, security.allowed_accessors) suit shared servers, and file accessor prefix settings limit which paths can be read. Note that setting denied_fs_accessor_prefix replaces the built-in defaults, so include acl, backups, config, orgs, secrets and users if you keep those protections.

Metrics

• Time to answer: minutes from hunt launch to results from 90% of online clients.
• Privilege count: number of users and API clients holding admin-equivalent permissions (target: a handful, reviewed monthly).
• Credential hygiene: API and client certificates within 30 days of expiry, and API clients unused for 90 days.

Framework mapping

Alternatives

Choose Velociraptor when you need the same forensic question answered across many hosts and can staff someone to own the server securely. Choose EDR live response when the estate is small and the EDR already collects what you need. Image the few systems that may go to court.

Common failure patterns

• CA key left on the server: anyone who takes the host can mint API keys and impersonate the server. Keep it offline.
• Basic authentication in production: weak password hashing and admin-resettable passwords undo the rest of the hardening.
• EXECVE and ARTIFACT_WRITER given out casually: these are admin-equivalent and amount to code execution on every endpoint.
• Untested hunts launched fleet-wide: the documentation warns that collecting a 100 MB file from 10,000 machines needs more than 1 TB of storage. Test on one or two hosts first.
• Nobody watching for rogue Velociraptor: attackers have installed it for remote access, so an unexpected client or frontend address should raise an alert.

Practitioner checklist

• Run the server on Linux as a low-privilege account, with a root-only writable configuration and the current release.
• Authenticate users through OIDC, OAuth2 or SAML with two-factor authentication enforced at the identity provider; retire Basic authentication.
• Remove CA.private_key from the running configuration and store the full configuration offline.
• Restrict the GUI with GUI.allowed_cidr or an SSH tunnel and keep the API bound to 127.0.0.1.
• Limit admin-equivalent permissions to named individuals and review them monthly; use wrapper artifacts instead of EXECVE.
• Inventory API clients, give each the api role plus the minimum needed, and track certificate expiry.
• Forward server and audit logs to a remote syslog host and alert on role grants and artifact edits.
• Keep the server in lockdown: true outside active incidents.
• Build X.509-encrypted offline collectors in advance for hosts that cannot run the client.
• Alert on Velociraptor installs and frontend connections that are not yours.

Standards and references

• Velociraptor: Securing the Velociraptor Deployment
• Velociraptor: Deployment Overview
• Velociraptor: Offline Collections
• Velociraptor: Hunting
• Velocidex: Velociraptor source repository and licence
• NIST: SP 800-86 Guide to Integrating Forensic Techniques into Incident Response
• Rapid7: Rapid7 and Velociraptor Join Forces
• Sophos: Velociraptor incident response tool abused for remote access

Related NHI Mgmt Group resources: Digital Forensics (DFIR) Guide · Incident Response Guide · Windows Forensic Artefacts Guide · Memory Forensics Guide · Service Account Security Guide