# Generaptor
## Introduction
Generaptor is a platform-agnostic command line tool to generate a [Velociraptor](https://github.com/velocidex/velociraptor) offline collector based on pre-configured or customizable collection profiles.
All platforms can generate collectors for all targets, there is no limitation thanks to Python on the generation side and velociraptor on the configuration repacking side.
Generation of Darwin collector is not implemented for the moment due to the lack of use case on our side. Feel free to open a pull request regarding this feature.
## Dependencies
Dependencies are listed in [pyproject.toml](pyproject.toml) under `dependencies` option.
## Setup
The setup is the same for Linux, Windows and Darwin as long as Python 3.12+ is
installed and registered in the PATH environment variable. Using a Python virtual
environment is recommended.
```bash
# install without interactive prompt support
python3 -m pip install git+https://github.com/cert-edf/generaptor
# install with interactive prompt support
python3 -m pip install 'generaptor[pick] @ git+https://github.com/cert-edf/generaptor'
```
## Basic Collector Generation
```bash
# First, we fetch latest stable release of velociraptor
generaptor update
# Then create a collector for windows for instance
generaptor generate -o /data/case/case-001/collectors/ windows
# keep the private key secret in a password vault to be able to decrypt the archive
# /data/case/case-001/collectors now contains a collector and its configuration file
```
## Advanced Collector Generation
Some options allow to customize collectors:
```bash
# Explore generate options using
generaptor generate -h
# Explore linux-specific options using
generaptor generate linux -h
# Explore windows-specific options using
generaptor generate windows -h
# Generate a single-device collector for windows
# (windows default collector collects all devices)
generaptor generate windows --device D:
# Collector targets customization
# (require interactive prompt support, see setup)
generaptor generate --custom windows
# Collector targets customization using a profile (non-interactive)
echo '{"targets":["WebServer/IIS"]}' > ~/.config/generaptor/windows/iis_server.json
generaptor generate --profile iis_server windows
```
## Expert Collector Generation
Generaptor can use optional configuration files put in `$HOME/.config/generaptor` directory to generate collectors.
Target and rules can be extended using this configuration directory.
VQL templates can also be modified to add custom artifacts or modify the collector behavior. Please refer to [Velociraptor documentation](https://docs.velociraptor.app/) to learn how to master VQL and write your own configuration files.
After starting generaptor for the first time, you can use the following commands to initialize the configuration directory
```bash
# Add variables for directories in current environment
export CACHE="${HOME}/.cache/generaptor"
export CONFIG="${HOME}/.config/generaptor"
# Copy header for each file
head -n 1 "${CACHE}/config/linux/rules.csv" > "${CONFIG}/linux/rules.csv"
head -n 1 "${CACHE}/config/linux/targets.csv" > "${CONFIG}/linux/targets.csv"
head -n 1 "${CACHE}/config/windows/rules.csv" > "${CONFIG}/windows/rules.csv"
head -n 1 "${CACHE}/config/windows/targets.csv" > "${CONFIG}/windows/targets.csv"
# Copy VQL templates
cp "${CACHE}/config/linux/collector.yml.jinja" "${CONFIG}/linux/"
cp "${CACHE}/config/windows/collector.yml.jinja" "${CONFIG}/windows/"
```
## Collection Processing
```bash
# Extract a collection
generaptor extract \
--directory /data/case/case-001/collection/ \
private.key.pem \
Collection_COMPUTERNAME_DEVICENAME_YYYY-mm-ddTHH-MM-SS.zip
```
## Past contributors (until version 10.0.2)
- [koromodako](https://github.com/koromodako)
- [SPToast](https://github.com/SPToast)
- [td2m](https://github.com/td2m)
Raw data
{
"_id": null,
"home_page": null,
"name": "generaptor",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": null,
"keywords": "cli, generator, velociraptor, offline, triage",
"author": null,
"author_email": "CERT-EDF <cert@edf.fr>",
"download_url": null,
"platform": null,
"description": "# Generaptor\n\n\n## Introduction\n\nGeneraptor is a platform-agnostic command line tool to generate a [Velociraptor](https://github.com/velocidex/velociraptor) offline collector based on pre-configured or customizable collection profiles.\n\nAll platforms can generate collectors for all targets, there is no limitation thanks to Python on the generation side and velociraptor on the configuration repacking side.\n\nGeneration of Darwin collector is not implemented for the moment due to the lack of use case on our side. Feel free to open a pull request regarding this feature.\n\n\n## Dependencies\n\nDependencies are listed in [pyproject.toml](pyproject.toml) under `dependencies` option.\n\n\n## Setup\n\nThe setup is the same for Linux, Windows and Darwin as long as Python 3.12+ is\ninstalled and registered in the PATH environment variable. Using a Python virtual\nenvironment is recommended.\n\n```bash\n# install without interactive prompt support\npython3 -m pip install git+https://github.com/cert-edf/generaptor\n# install with interactive prompt support\npython3 -m pip install 'generaptor[pick] @ git+https://github.com/cert-edf/generaptor'\n```\n\n\n## Basic Collector Generation\n\n```bash\n# First, we fetch latest stable release of velociraptor\ngeneraptor update\n# Then create a collector for windows for instance\ngeneraptor generate -o /data/case/case-001/collectors/ windows\n# keep the private key secret in a password vault to be able to decrypt the archive\n# /data/case/case-001/collectors now contains a collector and its configuration file\n```\n\n\n## Advanced Collector Generation\n\nSome options allow to customize collectors:\n\n```bash\n# Explore generate options using\ngeneraptor generate -h\n# Explore linux-specific options using\ngeneraptor generate linux -h\n# Explore windows-specific options using\ngeneraptor generate windows -h\n# Generate a single-device collector for windows\n# (windows default collector collects all devices)\ngeneraptor generate windows --device D:\n# Collector targets customization\n# (require interactive prompt support, see setup)\ngeneraptor generate --custom windows\n# Collector targets customization using a profile (non-interactive)\necho '{\"targets\":[\"WebServer/IIS\"]}' > ~/.config/generaptor/windows/iis_server.json\ngeneraptor generate --profile iis_server windows\n```\n\n\n## Expert Collector Generation\n\nGeneraptor can use optional configuration files put in `$HOME/.config/generaptor` directory to generate collectors.\n\nTarget and rules can be extended using this configuration directory.\n\nVQL templates can also be modified to add custom artifacts or modify the collector behavior. Please refer to [Velociraptor documentation](https://docs.velociraptor.app/) to learn how to master VQL and write your own configuration files.\n\nAfter starting generaptor for the first time, you can use the following commands to initialize the configuration directory\n\n```bash\n# Add variables for directories in current environment\nexport CACHE=\"${HOME}/.cache/generaptor\"\nexport CONFIG=\"${HOME}/.config/generaptor\"\n# Copy header for each file\nhead -n 1 \"${CACHE}/config/linux/rules.csv\" > \"${CONFIG}/linux/rules.csv\"\nhead -n 1 \"${CACHE}/config/linux/targets.csv\" > \"${CONFIG}/linux/targets.csv\"\nhead -n 1 \"${CACHE}/config/windows/rules.csv\" > \"${CONFIG}/windows/rules.csv\"\nhead -n 1 \"${CACHE}/config/windows/targets.csv\" > \"${CONFIG}/windows/targets.csv\"\n# Copy VQL templates\ncp \"${CACHE}/config/linux/collector.yml.jinja\" \"${CONFIG}/linux/\"\ncp \"${CACHE}/config/windows/collector.yml.jinja\" \"${CONFIG}/windows/\"\n```\n\n\n## Collection Processing\n\n```bash\n# Extract a collection\ngeneraptor extract \\\n --directory /data/case/case-001/collection/ \\\n private.key.pem \\\n Collection_COMPUTERNAME_DEVICENAME_YYYY-mm-ddTHH-MM-SS.zip\n```\n\n\n## Past contributors (until version 10.0.2)\n\n- [koromodako](https://github.com/koromodako)\n- [SPToast](https://github.com/SPToast)\n- [td2m](https://github.com/td2m)\n",
"bugtrack_url": null,
"license": null,
"summary": "A generator for Velociraptor-based offline collectors",
"version": "15.1.2",
"project_urls": {
"Bug Tracker": "https://github.com/cert-edf/generaptor/issues",
"Homepage": "https://github.com/cert-edf/generaptor",
"Repository": "https://github.com/cert-edf/generaptor"
},
"split_keywords": [
"cli",
" generator",
" velociraptor",
" offline",
" triage"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "cf4fa134e97e085e9f3d7ca785c1b61f872bf61ef4fbc96165c0b1f371884605",
"md5": "eac22ad43383e995dd8e738955f72196",
"sha256": "298b06c0da027ea9e30ac3994d869268cdf056711ac49435bfce7aa8a2ad73dd"
},
"downloads": -1,
"filename": "generaptor-15.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "eac22ad43383e995dd8e738955f72196",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 85351,
"upload_time": "2025-08-27T08:50:10",
"upload_time_iso_8601": "2025-08-27T08:50:10.565125Z",
"url": "https://files.pythonhosted.org/packages/cf/4f/a134e97e085e9f3d7ca785c1b61f872bf61ef4fbc96165c0b1f371884605/generaptor-15.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-27 08:50:10",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "cert-edf",
"github_project": "generaptor",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "generaptor"
}
JSON
