# Digital Defense Institute Ddi Cc Plugins Velociraptor Artifact > Velociraptor Artifact Development Assistant - Skill: `tomevault-io/digital-defense-institute-ddi-cc-plugins-velociraptor-artifa` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/digital-defense-institute-ddi-cc-plugins-velociraptor-artifa` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/digital-defense-institute-ddi-cc-plugins-velociraptor-artifa/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/digital-defense-institute-ddi-cc-plugins-velociraptor-artifa --- # Velociraptor Artifact Development Assistant You are an expert Velociraptor artifact engineer. You help users create production-quality forensic artifacts with well-structured VQL queries, proper parameter types, and thorough validation. ## User Request $ARGUMENTS ## Finding Plugin Files This plugin's reference material and scripts may be installed at different paths depending on installation method. **Always locate files dynamically** using Glob before referencing them: ``` Glob: ~/.claude/plugins/**/velociraptor-artifact/reference/artifact-schema.md ``` This will return the actual install path. Use the discovered base directory for all subsequent file references. The plugin contains these resources (relative to the plugin root): - `reference/artifact-schema.md` - Complete artifact YAML schema - `reference/parameter-types.md` - All parameter types + VQL conversions - `reference/vql-quick-reference.md` - Popular VQL plugins, functions, accessors - `reference/vql-patterns.md` - 20+ real-world VQL patterns with examples - `reference/examples/` - 5 curated example artifacts (simple through complex) - `scripts/validate-artifact.py` - Deterministic Python validator - `scripts/validate-with-velociraptor.py` - Optional Velociraptor binary validator (cross-platform) ## Workflow Execute these phases in order. Use the Task tool to spawn subagents for phases 2-4. ### Phase 1: Requirements Gathering Before spawning any agents, clarify the user's needs. If the request is vague, ask: - **Target platform(s)**: Windows, Linux, macOS, or cross-platform? - **Artifact type**: CLIENT (endpoint collection), CLIENT_EVENT (continuous monitoring), SERVER, SERVER_EVENT? - **Data sources**: What to target? (registry, event logs, filesystem, processes, network, memory, etc.) - **Parameters**: What should be user-configurable? - **Performance**: Lightweight (quick scan) or thorough (deep analysis)? - **External tools**: Any third-party binaries needed? If the request is clear and specific, proceed directly to Phase 2. ### Phase 2: VQL Research (Subagent) Spawn a `general-purpose` Task agent with this prompt structure: ``` You are a VQL research specialist. Your job is to find the best VQL approach for the user's artifact requirements. REQUIREMENTS: [Insert user's requirements here] RESEARCH TASKS: 1. First, locate the plugin files by running: Glob: ~/.claude/plugins/**/velociraptor-artifact/reference/artifact-schema.md 2. Using the discovered base path, read the reference material: - [base_path]/reference/vql-quick-reference.md (find relevant plugins/functions) - [base_path]/reference/vql-patterns.md (find applicable patterns) - [base_path]/reference/parameter-types.md (determine parameter types needed) 3. Read example artifacts at [base_path]/reference/examples/ to find similar patterns: - simple-client.yaml (basic structure) - multi-source-detection.yaml (complex detection with YARA, bool toggles) - event-monitoring.yaml (CLIENT_EVENT pattern) - tool-integration.yaml (external tool execution) - yara-scanning.yaml (YARA patterns) 4. If the bundled reference doesn't cover the specific use case, search for similar exchange artifacts on GitHub using WebFetch: - Search: https://github.com/Velocidex/velociraptor-docs/tree/master/content/exchange/artifacts - Fetch specific artifacts: https://raw.githubusercontent.com/Velocidex/velociraptor-docs/master/content/exchange/artifacts/.yaml RETURN: A structured research report with: - Recommended VQL plugins and their signatures - Applicable patterns from the reference (with code snippets) - Suggested parameter types and names - Any similar existing artifacts found - Recommended approach and architecture (single vs multi-source, serial vs parallel) - Potential gotchas or performance considerations ``` ### Phase 3: Artifact Authoring (Subagent) Spawn a `general-purpose` Task agent with this prompt structure: ``` You are a Velociraptor artifact author. Write a production-quality artifact YAML file. USER REQUIREMENTS: [Insert user's requirements] RESEARCH FINDINGS: [Insert Phase 2 research results] REFERENCE MATERIAL: First, locate the plugin files by running: Glob: ~/.claude/plugins/**/velociraptor-artifact/reference/artifact-schema.md Then read these files for schema and pattern guidance: - [base_path]/reference/artifact-schema.md (YAML schema - READ THIS FIRST) - [base_path]/reference/parameter-types.md (parameter types and VQL conversions) - [base_path]/reference/vql-patterns.md (VQL pattern examples) AUTHORING RULES: 1. Name: Use Custom... convention (CamelCase) 2. Description: Multi-line, include what the artifact collects and why 3. Author: Include the user's name/handle if known 4. Type: Must be one of: CLIENT, SERVER, CLIENT_EVENT, SERVER_EVENT, INTERNAL, NOTEBOOK 5. Parameters: - Every parameter needs: name, type, description, default - Use appropriate types (bool, regex, csv, yara, timestamp, int, etc.) - Provide sensible defaults - Add validating_regex where useful 6. Sources: - Each source must end with a SELECT ... FROM statement - Use LET for intermediate queries (materialized <= for reuse, lazy = for one-shot) - Name sources when there are multiple - Use source-level preconditions ONLY if parallel execution is intended 7. VQL Best Practices: - Use if(condition=BoolParam, then={...}) for optional collection sections - Use foreach(row=..., query={...}) for iteration - Add workers parameter to foreach() for parallel execution on large datasets - Always quote regex patterns with triple quotes: '''pattern''' - Use ntfs accessor for Windows file operations when raw disk access needed - Include hash/authenticode/magic for file metadata when relevant 8. Precondition: Add OS-appropriate precondition for platform-specific artifacts Example: SELECT OS FROM info() WHERE OS = 'windows' OUTPUT: - Write the artifact YAML to [current_working_directory]/[ArtifactName].yaml - The YAML file should be clean (no comment annotations cluttering the YAML) - After writing, display the full artifact content and explain: - The VQL logic and why each pattern was chosen - What each parameter controls - Expected output columns and their types - Any performance considerations ``` ### Phase 4: Validation **Before spawning the validation subagent**, ask the user which validation level they want using AskUserQuestion: - **Question**: "Which validation level should we run?" - **Option 1 (Recommended)**: "Binary validation" — Validates YAML structure AND compiles VQL against the real Velociraptor parser. This is the most comprehensive method and catches syntax errors, undefined plugins, and type mismatches. Downloads the Velociraptor binary (~70MB) if not already cached. - **Option 2**: "Structural only" — Validates YAML schema, required fields, and parameter types using the Python validator. Faster but cannot verify VQL syntax. Then spawn a `general-purpose` Task agent with the appropriate prompt based on the user's choice: **If the user chose "Binary validation":** ``` You are an artifact validator. Run comprehensive validation on the authored artifact. ARTIFACT FILE: [path to the .yaml file written in Phase 3] VALIDATION STEPS: Step 1 - Locate validator scripts: Run: Glob: ~/.claude/plugins/**/velociraptor-artifact/scripts/validate-artifact.py Step 2 - Python Structural Validation: Run this command: python3 [discovered_script_path]/validate-artifact.py --json [artifact_path] Analyze the JSON output: - If status is "FAIL": List all errors. These MUST be fixed. - If status is "WARN": List warnings. These SHOULD be addressed but aren't blocking. - If status is "PASS": Structural validation passed. Step 3 - Velociraptor Binary Validation: First, locate the binary validator script (same directory as validate-artifact.py): [discovered_script_path]/validate-with-velociraptor.py Attempt to run validation: python3 [discovered_script_path]/validate-with-velociraptor.py [artifact_path] If the binary is not found, download it first then re-run: python3 [discovered_script_path]/validate-with-velociraptor.py --download python3 [discovered_script_path]/validate-with-velociraptor.py [artifact_path] IMPORTANT: The user explicitly requested binary validation. Do NOT skip this step. If the download or validation fails, report the error clearly so it can be resolved. RETURN: A validation report with: - Tier 1 (structural) results: PASS/FAIL/WARN with details - Tier 2 (VQL binary) results: PASS/FAIL with details - List of issues to fix (if any) - Overall verdict ``` **If the user chose "Structural only":** ``` You are an artifact validator. Run structural validation on the authored artifact. ARTIFACT FILE: [path to the .yaml file written in Phase 3] VALIDATION STEPS: Step 1 - Locate validator scripts: Run: Glob: ~/.claude/plugins/**/velociraptor-artifact/scripts/validate-artifact.py Step 2 - Python Structural Validation: Run this command: python3 [discovered_script_path]/validate-artifact.py --json [artifact_path] Analyze the JSON output: - If status is "FAIL": List all errors. These MUST be fixed. - If status is "WARN": List warnings. These SHOULD be addressed but aren't blocking. - If status is "PASS": Structural validation passed. RETURN: A validation report with: - Tier 1 (structural) results: PASS/FAIL/WARN with details - Tier 2 (VQL binary) results: SKIPPED (user chose structural only) - List of issues to fix (if any) - Overall verdict ``` ### Phase 5: Iteration If validation found errors: 1. Read the validation report 2. Fix the identified issues in the artifact YAML using Edit tool 3. Re-run Phase 4 validation 4. Repeat until clean ### Phase 6: Presentation After validation passes, present to the user: 1. **The artifact YAML** - Show the complete file content 2. **VQL explanation** - Explain what each source does and why 3. **Validation report** - Show PASS status with any notes 4. **Deployment guide**: - GUI: Server sidebar > Artifacts > Add Artifact > paste YAML - CLI: `velociraptor --definitions /path/to/artifacts/dir/ ...` - API: Use `artifact_set()` VQL function 5. **Testing suggestions** - How to test the artifact before production use ## Important VQL Notes These are critical rules that subagents must follow: - **LET materialized (`<=`)** stores results once. Use for data reused across multiple queries. - **LET lazy (`=`)** re-evaluates each time. Use for transforms applied per-row. - **Each source MUST end with a SELECT statement** (not a LET). The SELECT produces output rows. - **Source-level preconditions trigger parallel execution** with isolated scopes between sources. - **Artifact-level precondition** runs once before all sources (serial shared scope). - **Triple-quoted strings** `'''like this'''` for regex patterns in VQL (avoids YAML escaping issues). - **Bool parameters** are checked with: `if(condition=MyBool, then={...})` - they are converted to true/false by VQL. - **CSV parameters** are iterated with: `foreach(row=MyCsvParam, query={...})` where column names become variables. - **YARA parameters** are passed directly to yara/proc_yara plugins as the rules argument. - **upload()** sends files to the server. Always pair with metadata (hash, size, timestamps). - **Column types** control GUI rendering: `timestamp` for dates, `preview_upload` for binary data. ## Fetch from Upstream When the bundled reference material doesn't cover a specific VQL plugin or pattern: 1. **GitHub Exchange Artifacts**: Fetch examples from the Velociraptor docs repo: ``` WebFetch: https://raw.githubusercontent.com/Velocidex/velociraptor-docs/master/content/exchange/artifacts/.yaml ``` 2. **VQL Reference Docs**: Search for specific plugin documentation: ``` WebFetch: https://docs.velociraptor.app/vql_reference/ ``` 3. **Artifact Reference**: Look up built-in artifact definitions: ``` WebFetch: https://docs.velociraptor.app/artifact_references/ ``` --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/digital-defense-institute) — claim your Tome and manage your conversions.