Rust · Open Source · Endpoint Security R&D

Crustacian — a Rust endpoint CLI for ClamAV and blue-team operations

Crustacian is shifting from a local antivirus helper into an endpoint security toolkit: ClamAV lifecycle management, repeatable scans, local evidence capture, EDR telemetry, server-side ingest, and safe response-planning stages for security teams.

🔗 GitHub Repository ▶ Install Now

Self-host it. Automate it. Build endpoint evidence into your own security workflows.

Quick Overview
  • ✅ Rust-based, single binary endpoint CLI
  • ✅ Installs and configures ClamAV and FreshClam
  • ✅ Quick, full, and custom path scans
  • ✅ Local scan evidence, throughput, and ETA
  • ✅ SIEM-ready telemetry and EDR R&D planning artifacts
  • ✅ Proposed ingest, backpressure, and CI/CD lanes
Built for lab environments, managed endpoints, SOC workflows, and security research where transparent local evidence matters before enforcement is enabled. Server-side ingestion and response connectors are planned as separate, auditable components.

What is Crustacian?

Crustacian is a Rust CLI that wraps ClamAV in a clean operational interface while laying the groundwork for endpoint detection and response research. It handles the heavy lifting:

  • Detecting or bootstrapping a ClamAV installation
  • Creating tuned configuration files for clamd and FreshClam
  • Running scans and surfacing results clearly
  • Saving summaries and infection lists for later use
  • Producing local endpoint telemetry and snapshot hashes for SIEM pipelines

You stay in control of your environment — Crustacian is self-hosted, local-first, and built to integrate with existing blue-team tools without enabling destructive response actions by default.

Key properties

Language
Rust
License
MIT
Scope
Endpoint security R&D
Engine
ClamAV + FreshClam

Crustacian remains local-first by default. SIEM delivery, identity response, and containment workflows are staged as explicit, auditable integrations rather than hidden background behavior.

Features

Bootstrap ClamAV

Initialize or repair a ClamAV environment on supported platforms. Generate configs, set log paths, and keep FreshClam ready to update signatures on schedule.

Run Endpoint Scans

Run quick, full, or custom directory scans from the interactive CLI. See infections in real time and export results for follow-up analysis or automation.

Telemetry & Response R&D

Generate NDJSON events, endpoint snapshots, SHA-256 evidence hashes, and disabled response plans for SIEM, authentik, LDAP, and containment research.

EDR + AV integration plan

Crustacian can become a combined antivirus endpoint and EDR telemetry agent by separating detection, evidence collection, transport, and response control. ClamAV remains the AV engine; Crustacian owns orchestration, local event normalization, and fleet-safe delivery.

The integrations below are intentionally staged. They enable visibility first, dry-run response second, and approval-gated containment only after audit trails and rollback behavior are proven.

Endpoint AV

Manage ClamAV and FreshClam lifecycle, signature health, scan policy, quarantine metadata, and infection evidence hashes from one local agent.

Endpoint Detection

Spool normalized file, process, scan, policy, and integrity events as NDJSON with stable endpoint IDs and monotonic sequence numbers.

SIEM/SOAR Delivery

Ship events to syslog, OpenSearch, Splunk HEC, Elastic, Sentinel-compatible collectors, or webhook receivers through pluggable exporters.

Response Connectors

Keep host isolation, authentik/LDAP actions, ticket creation, and quarantine workflows in dry-run mode until policy approval is explicit.

Server-side ingest and telemetry

Ingest API

A dedicated receiver should accept signed batches over mTLS or token-authenticated HTTPS, validate schema versions, deduplicate by endpoint sequence, and return precise retry hints.

Telemetry Pipeline

Server workers normalize events into hot storage, object archives, alert queues, and SIEM outputs while preserving raw endpoint evidence for forensic review.

Backpressure

Endpoints should use bounded local spools, exponential retry, priority lanes for detections, server rate-limit headers, and drop-safe summaries when collectors lag. 

endpoint agent
  -> local spool
  -> batch sender with retry and rate-limit handling
  -> ingest API
  -> validation queue
  -> telemetry store + SIEM exporters + response review queue

CI/CD lanes

Endpoint Agent

Format, lint, test, audit dependencies, build cross-platform binaries, sign release artifacts, and publish checksums for managed deployment systems.

Server Ingest

Run API tests, schema compatibility checks, container builds, image scans, migration tests, and environment promotion gates before deployment.

Site and Docs

Validate static content and publish architecture docs, schemas, runbooks, and release notes alongside endpoint and server artifacts.

WASM CLI preview

The browser build is intended as a safe, inspection-only CLI for demos, parser validation, and SOC workflow reviews. It can show the endpoint telemetry shape and ingest batch format without touching ClamAV services, the local filesystem, identity systems, or containment controls.

The sample run below mirrors the Rust endpoint event model and shows what a sandboxed WebAssembly build would emit before an endpoint sends data to the server-side ingest API.

crustacian-wasm · browser telemetry sample
$ crustacian-wasm telemetry sample --mode browser --emit-ingest-batch Initializing WASM runtime... Runtime: browser sandbox Endpoint ID: demo-browser-endpoint ClamAV engine: unavailable in browser; using simulated scan metadata Generated endpoint event: schema_version: crustacian.endpoint.telemetry.v0 event_kind: scan.completed classifier: clamav.scan.clean severity: informational confidence: 0.72 isolation_recommended: false Generated ingest batch: schema_version: crustacian.ingest.batch.v0 events: 1 target: /v1/ingest Result: sample batch ready for parser and ingest testing.

Basic usage

Once you’ve cloned the repository and built the project with Cargo, launch the interactive CLI to initialize ClamAV, scan endpoints, and generate local telemetry artifacts:

Build

# Clone the repository
git clone https://github.com/CharlesDerek/crustacian.git
cd crustacian

# Build in release mode
cargo build --release

Run the interactive CLI

# On Windows (example)
.\target\release\crustacian.exe

# On Linux / macOS
./target/release/crustacian

Example workflow

# 1. Initialize / repair ClamAV environment
#    - Install / locate ClamAV
#    - Write clamd & freshclam config files
#    - Run initial signature update

# 2. Run a new scan
#    - Quick scan: user folders / temp
#    - Full scan: whole volume
#    - Custom scan: specify paths

# 3. Review history and endpoint telemetry
#    - View past scan summaries
#    - Inspect infection lists
#    - Generate SIEM-ready local event artifacts
#    - Draft disabled response plans for review