tools/

osctrl toolset

Fast and efficient osquery management.

Development, migration, load-testing, and packaging helpers used by the osctrl project. Run commands from the repository root unless a section says otherwise.

api_tester.py

Comprehensive Python3 test suite for the osctrl-api service. Tests all API endpoints systematically and provides detailed pass/fail reporting. Useful for regression testing after making changes to the API.

Basic usage:

# With login credentials
$ python3 api_tester.py http://localhost:9002 --username admin --password admin --env <env-uuid>

# With existing token
$ python3 api_tester.py http://localhost:9002 --token <api-token> --env <env-uuid>

# Skip authentication tests
$ python3 api_tester.py http://localhost:9002 --skip-auth

# Verbose output
$ python3 api_tester.py http://localhost:9002 --token <token> --env <env-uuid> --verbose

# Disable SSL verification (for self-signed certs)
$ python3 api_tester.py https://api.example.com --token <token> --env <env-uuid> --insecure

Options:

• --username, -u: Username for authentication
• --password, -p: Password for authentication
• --env, -e: Environment UUID for testing (required for most tests)
• --token, -t: Use existing API token instead of logging in
• --skip-auth: Skip authentication tests
• --verbose, -v: Show detailed request/response information
• --insecure, -k: Disable SSL certificate verification

The script tests all API endpoints including:

• Health checks and status endpoints
• Authentication (login)
• Environments, platforms, nodes
• Tags, settings, users
• Queries and carves (if enabled)
• Audit logs (if enabled)

It requires to install requests with pip install requests.

fake_news_go

Console-native load harness for osctrl-tls and osctrl-api.

• steady mode keeps a fixed load running until interrupted with Ctrl+C, q, or Q
• sweep mode ramps node count by stage and stops on the first threshold breach, or exits early with Ctrl+C, q, or Q
• dashboard display mode renders a dense termui terminal dashboard
• writes fake_news_report.json after sweep completion or steady shutdown
• uses fake_news_state.json as the default persisted node-state file
• can auto-discover environment UUIDs and enroll secrets from osctrl-api with --discover-envs
• simulates distributed-query write results internally, without shelling out to osqueryi

Quick example:

$ go run ./tools/fake_news_go --tls-url http://localhost:9000 --env <env-uuid> --secret <secret> --display-mode dashboard

Automatic discovery from osctrl-api:

$ go run ./tools/fake_news_go \
  --tls-url http://localhost:9000 \
  --api-url http://localhost:9002 \
  --api-username admin \
  --api-password admin \
  --discover-envs \
  --display-mode dashboard

Mixed TLS + API sweep:

$ go run ./tools/fake_news_go \
  --tls-url http://localhost:9000 \
  --api-url http://localhost:9002 \
  --api-username admin \
  --api-password admin \
  --env <env-uuid> \
  --secret <secret> \
  --mode sweep \
  --display-mode dashboard

Helper targets from tools/fake_news_go:

$ make -C tools/fake_news_go dashboard ENV_UUID=<env-uuid> SECRET=<secret>
$ make -C tools/fake_news_go dashboard DISCOVER_ENVS=1 API_URL=http://localhost:9002 API_USERNAME=admin API_PASSWORD=admin
$ make -C tools/fake_news_go sweep ENV_UUID=<env-uuid> SECRET=<secret>

See tools/fake_news_go/README.md for details.

live_updates_rollout

Operational checker for the SSE live-update rollout. It logs in to one or more API replicas, opens SSE streams through the proxy/frontend URL, verifies stream.ready, checks subscriber cleanup through /api/v1/health/status, and can verify rollback with --expect-disabled.

$ go run ./tools/live_updates_rollout \
    --api-url https://api-a.example.com,https://api-b.example.com \
    --proxy-url https://osctrl.example.com \
    --username "$OSCTRL_USER" \
    --password "$OSCTRL_PASS" \
    --min-apis 2 \
    --connections 32

Live update rollout checklist

Run this against a staging deployment with at least two osctrl-api replicas, two osctrl-tls replicas, Redis, the normal frontend/proxy path, and health reporting enabled.

First verify the disabled baseline:

$ go run ./tools/live_updates_rollout \
    --api-url https://api-a.example.com,https://api-b.example.com \
    --proxy-url https://osctrl.example.com \
    --username "$OSCTRL_USER" \
    --password "$OSCTRL_PASS" \
    --min-apis 2 \
    --expect-disabled

Enable the same non-empty event namespace on every API and TLS replica:

service:
  eventsEnabled: true
  eventsNamespace: staging-live-updates

Restart all API and TLS replicas, then run the fleet canary:

$ go run ./tools/live_updates_rollout \
    --api-url https://api-a.example.com,https://api-b.example.com \
    --proxy-url https://osctrl.example.com \
    --username "$OSCTRL_USER" \
    --password "$OSCTRL_PASS" \
    --min-apis 2 \
    --topics fleet \
    --connections 32 \
    --timeout 60s

Verify query/carve topics against one test environment UUID:

$ go run ./tools/live_updates_rollout \
    --api-url https://api-a.example.com,https://api-b.example.com \
    --proxy-url https://osctrl.example.com \
    --username "$OSCTRL_USER" \
    --password "$OSCTRL_PASS" \
    --min-apis 2 \
    --env "$ENV_UUID" \
    --topics queries,carves \
    --connections 16 \
    --timeout 60s

For two API / two TLS recovery, hold streams open while restarting replicas:

$ go run ./tools/live_updates_rollout \
    --api-url https://api-a.example.com,https://api-b.example.com \
    --proxy-url https://osctrl.example.com \
    --username "$OSCTRL_USER" \
    --password "$OSCTRL_PASS" \
    --min-apis 2 \
    --topics fleet \
    --connections 32 \
    --timeout 3m \
    --hold 90s

While it prints HOLD streams open, restart one API replica and one TLS replica, wait for them to become healthy, then restart the second API and TLS replicas. The command must finish with cleanup and health PASS lines. service_status currently stores one TLS heartbeat row, so confirm the two-TLS-replica part from the orchestrator health/readiness view during the hold window.

Run a larger load and cleanup pass:

$ go run ./tools/live_updates_rollout \
    --api-url https://api-a.example.com,https://api-b.example.com \
    --proxy-url https://osctrl.example.com \
    --username "$OSCTRL_USER" \
    --password "$OSCTRL_PASS" \
    --min-apis 2 \
    --topics fleet \
    --connections 64 \
    --timeout 90s

Finally, disable live updates on every API and TLS replica, restart them, and rerun the disabled baseline command. Rollback is complete when features report events disabled and /api/v1/events returns unavailable through the proxy.

json2yaml-config

Go tool to convert old pre-0.5.0 JSON configuration into the YAML format used by osctrl-tls and osctrl-api. The converter accepts the legacy service, database, Redis, JWT, SAML, logger, and carver files, but only emits current TLS or API service configuration.

# Convert an old TLS configuration with graylog logger and S3 carver
$ go run ./tools/json2yaml-config -service tls \
    -config config/tls.json \
    -db config/db.json \
    -redis config/redis.json \
    -logger config/graylog.json \
    -carver config/carver_tls.json \
    -output tls.yml

# Convert an old API configuration with SAML and print to stdout
$ go run ./tools/json2yaml-config -service api \
    -config config/api.json \
    -db config/db.json \
    -redis config/redis.json \
    -jwt config/jwt.json \
    -saml config/saml.json \
    -output -

Options:

• -service: Service to convert: tls or api. Required.
• -config: Path to the old tls.json or api.json. Required.
• -db: Path to the old db.json file (optional, defaults are used if omitted)
• -redis: Path to the old redis.json file (optional, defaults are used if omitted)
• -jwt: Path to the old jwt.json file (optional, API only)
• -saml: Path to the old saml.json file (optional, API only)
• -logger: Path to the old logger JSON file, keyed by logger type: graylog, splunk, elastic, logstash, kinesis, s3 or kafka (optional)
• -carver: Path to the old S3 carver JSON file (optional)
• -output: Path to write the YAML output to (default: <service>.yml, use - for stdout)

Fields that did not exist in the old JSON configuration (osquery, osctrld, TLS termination, debug, OIDC...) are filled with the same defaults as the sample files in deploy/config/. Review the generated file before using it, in particular auditLog (emitted as false since the option did not exist pre 0.5.0) and the osquery section.

fake_logging.py

Script to simulate HTTP logging services (Graylog, Splunk...) for osctrl and check if logs are being sent. It is just an HTTP catchall service.

$ python3 fake_logging.py 1234

fake_news.py

Script to simulate load for osctrl. It can effectively simulate thousands of osquery nodes, generating fake status and result logs, generate results for on-demand queries and it re-enrolls nodes if they have been removed.

$ python3 fake_news.py -h
usage: fake_news.py [-h] [--secret SECRET] [--url URL] [--nodes NODES] [--status STATUS] [--result RESULT] [--config CONFIG] [--query QUERY] [--read [READ]] [--write [WRITE]] [--verbose]

Script to simulate load for osctrl

optional arguments:
  -h, --help            show this help message and exit
  --url URL, -u URL     URL for osctrl-tls used to enroll nodes (default: http://localhost:9000/)
  --nodes NODES, -n NODES
                        Number of random nodes to simulate (default: 5)
  --status STATUS, -S STATUS
                        Interval in seconds for status requests to osctrl (default: 60)
  --result RESULT, -R RESULT
                        Interval in seconds for result requests to osctrl (default: 60)
  --config CONFIG, -c CONFIG
                        Interval in seconds for config requests to osctrl (default: 45)
  --query QUERY, -q QUERY
                        Interval in seconds for query requests to osctrl (default: 30)
  --read [READ], -r [READ]
                        JSON file to read nodes from
  --write [WRITE], -w [WRITE]
                        JSON file to write nodes to
  --verbose, -v         Enable verbose output (default: False)

required arguments:
  --secret SECRET, -s SECRET
                        Secret to enroll nodes for osctrl-tls (default: None)

It requires to install requests with pip install requests.

build-osctrl-deb.sh

Script to repack the osquery DEB package with the osctrl configuration files to be used with the osctrl-tls service. It is recommended to execute as root to avoid permission issues with the tar command and the existing permissions of the osquery DEB package.

$ ./build-osctrl-deb.sh -h

Usage: ./tools/build-osctrl-deb.sh [-h|--help] [PARAMETER [ARGUMENT]] [PARAMETER [ARGUMENT]] ...

Options:
  -h          Show this help message and exit
  -c CERT     Path to the osquery certificate file
  -s SECRET   Path to the osquery secret file (default: osquery.secret)
  -f FLAGS    Path to the osquery flags file (default: osquery.flags)
  -i DEB      Path to the osquery DEB file. Required.
  -o DEB      Path to the osctrl DEB file. Required.
  -x          Clear the temporary directory after the process
  -v          Enable verbose mode with 'set -x'

Example:
  ./tools/build-osctrl-deb.sh -i osquery_5.23.1-1.linux.amd64.deb -o osquery-osctrl_5.23.1-1_amd64.deb

build-osctrl-pkg.sh

Script to repack the osquery PKG package with the osctrl configuration files to be used with the osctrl-tls service.

$ ./build-osctrl-pkg.sh -h

Usage: ./build-osctrl-pkg.sh [-h|--help] [PARAMETER [ARGUMENT]] [PARAMETER [ARGUMENT]] ...

Options:
  -h          Show this help message and exit
  -n NAME     Name to use for the package (default: osctrl)
  -V VERSION  Version to use for the package (default: 1.0)
  -c CERT     Path to the osquery certificate file
  -s SECRET   Path to the osquery secret file (default: osquery.secret)
  -f FLAGS    Path to the osquery flags file (default: osquery.flags)
  -i PKG      Path to the osquery PKG file. Required.
  -o PKG      Path to the osctrl PKG file. Required.
  -k          Generate a PKG without osquery. Only osctrl files.
  -x          Clear the temporary directory after the process
  -v          Enable verbose mode with 'set -x'

Example:
  ./tools/build-osctrl-pkg.sh -i osquery_5.23.1.pkg -o osquery-osctrl_5.23.1.pkg