Velociraptor Artifact YAML Format & Packaging — Comprehensive Research

name: Custom.Artifact.Name
description: |
  One-sentence summary of what this artifact does.
  
  Additional details here.

sources:
  - query: |
      SELECT * FROM info()
      LIMIT 10

name: Custom.AIToolEvidence

sources:
  - name: WindowsData
    precondition: SELECT OS FROM info() WHERE OS = 'windows'
    query: |
      SELECT * FROM glob(globs='C:\\Users\\*\\AppData\\...')

  - name: LinuxData
    precondition: SELECT OS FROM info() WHERE OS = 'linux'
    query: |
      SELECT * FROM glob(globs='/home/*/.config/...')

  - name: MacOSData
    precondition: SELECT OS FROM info() WHERE OS = 'darwin'
    query: |
      SELECT * FROM glob(globs='/Users/*/Library/Application Support/...')

# In each OS-specific artifact:
name: Windows.Applications.Chrome.History
precondition: SELECT OS From info() where OS = 'windows'
...

# Then create a unified alias in a Generic artifact:
name: Generic.Detection.Yara.Glob
aliases:
  - Windows.Detection.Yara.Glob
  - Linux.Detection.Yara.Glob
  - MacOS.Detection.Yara.Glob

# Windows only
precondition: SELECT OS FROM info() WHERE OS = 'windows'

# Linux only
precondition: SELECT OS FROM info() WHERE OS = 'linux'

# macOS only
precondition: SELECT OS FROM info() WHERE OS = 'darwin'

# Linux + macOS (not arm64)
precondition: SELECT OS FROM info() WHERE OS =~ 'linux|darwin' AND NOT Architecture = 'arm64'

# All platforms (no precondition needed, or)
precondition: SELECT TRUE FROM scope()

# Admin privilege check (any OS)
precondition: SELECT * FROM info() WHERE IsAdmin

-- Windows paths with drive letter
LET RootPath <= pathspec(Path=Root, accessor=Accessor)

-- Use accessor 'auto' for cross-platform (auto-selects OS/file/ntfs)
FROM glob(globs=PathGlob, accessor=Accessor)

-- Parse user from path (cross-platform pattern)
parse_string_with_regex(regex="/Users/(?P<User>[^/]+)", string=OSPath).User
-- or on Windows:
parse_string_with_regex(regex="\\\\Users\\\\(?P<User>[^\\\\]+)", string=OSPath).User

# Example from Generic.Collectors.File
parameters:
  - name: collectionSpec
    type: csv
    default: |
      Glob
      Users\*\NTUser.dat

sources:
  - query: |
      LET RootPath <= pathspec(Path=Root, accessor=Accessor)
      LET specs = SELECT RootPath + Glob AS Glob
        FROM collectionSpec
      LET hits = SELECT OSPath AS SourceFile, Size,
                        Mtime AS Modified, Ctime AS Changed,
                        Btime AS Created, Atime AS LastAccessed
        FROM glob(globs=specs.Glob, accessor=Accessor)
        WHERE NOT IsDir
         AND (Size <= MaxFileSize OR (log(message="Skipping...") AND FALSE))
      
      SELECT *, upload(file=SourceFile, accessor=Accessor, mtime=Modified) AS Upload
      FROM hits

-- Read a registry value
SELECT Data FROM reg_read(path='HKEY_LOCAL_MACHINE\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\Run')

-- Glob registry keys
SELECT FullPath, Data, Mtime FROM glob(globs='HKEY_LOCAL_MACHINE\\SOFTWARE\\**', accessor='registry')

-- Parse specific values
SELECT Key, Data FROM reg_key(path='HKEY_LOCAL_MACHINE\\SOFTWARE\\MyApp')

-- Standard pattern (from Windows.Applications.Chrome.History)
LET history_files = SELECT * FROM foreach(
  row={
     SELECT Uid, Name AS User, expand(path=Directory) AS HomeDirectory
     FROM Artifact.Windows.Sys.Users()
     WHERE Name =~ userRegex
  },
  query={
     SELECT User, OSPath, Mtime
     FROM glob(globs=historyGlobs, root=HomeDirectory)
  })

SELECT * FROM foreach(row=history_files,
  query={
    SELECT User, url AS visited_url, title, visit_count
    FROM sqlite(file=OSPath, query=urlSQLQuery)
  })

-- Parse JSON lines (one JSON object per line)
SELECT timestamp(epoch=atoi(string=timestamp_str)) AS Timestamp,
       message AS Message,
       level AS Level
FROM parse_json(filename=OSPath, accessor='file')

-- Or for newline-delimited JSON:
SELECT * FROM parse_lines(filename=OSPath)
WHERE line =~ '^{'
LET parsed <= parse_json(data=line)

-- For structured JSON files:
SELECT * FROM parse_json(filename=OSPath)

-- Pattern from Linux.Network.NetstatEnriched
SELECT Pid, Name, Exe, CommandLine, Username
FROM pslist()
WHERE Name =~ ProcessNameRegex
  AND Exe =~ ProcessPathRegex
  AND CommandLine =~ CommandLineRegex
  AND Username =~ UsernameRegex

-- Pattern from Linux.Network.NetstatEnriched
SELECT Laddr.IP AS Laddr, Laddr.Port AS Lport,
       Raddr.IP AS Raddr, Raddr.Port AS Rport,
       Pid, Status,
       process_tracker_get(id=Pid).Data AS ProcInfo,
       join(array=process_tracker_callchain(id=Pid).Data.Name, sep=" -> ") AS CallChain
FROM connections()
WHERE Status =~ ConnectionStatusRegex
 AND Raddr =~ IPRegex
 AND ProcInfo.Name =~ ProcessNameRegex

-- Basic query
SELECT * FROM sqlite(file='/path/to/db.sqlite', query='SELECT * FROM table_name')

-- With timestamp conversion (Chrome uses Windows filetime * 10)
SELECT timestamp(winfiletime=visit_time * 10) AS visit_time
FROM sqlite(file=OSPath, query=urlSQLQuery)

-- Parameterized SQL query
parameters:
  - name: urlSQLQuery
    default: |
      SELECT url, title, visit_count FROM urls

-- Single JSON object per file
SELECT * FROM parse_json(filename=OSPath)

-- NDJSON (one JSON per line)
SELECT * FROM parse_lines(filename=OSPath)
WHERE line =~ '^{'
-- Then parse each line:
LET Parsed <= parse_json(data=line)

-- Metadata only (no upload)
SELECT OSPath, Size, Mtime, Ctime, Atime, Btime
FROM glob(globs=PathGlob)

-- Upload files with metadata
SELECT OSPath AS SourceFile, Size, Mtime AS Modified,
       upload(file=OSPath, accessor=Accessor) AS Upload
FROM glob(globs=PathGlob, accessor=Accessor)
WHERE NOT IsDir

-- Conditional upload with size limits
SELECT *, if(condition=Size < MaxFileSize,
        then=upload(file=OSPath),
        else=NULL) AS Upload
FROM glob(globs=PathGlob)
WHERE NOT IsDir

-- Build paths for different OSes
LET WindowsPaths = SELECT * FROM glob(globs='C:\\Users\\*\\AppData\\Roaming\\**\\config.json')
LET LinuxPaths = SELECT * FROM glob(globs='/home/*/.config/**/config.json')
LET MacOSPaths = SELECT * FROM glob(globs='/Users/*/Library/Application Support/**/config.json')

-- Use expand() to resolve user home directories
SELECT expand(path=Directory) AS HomeDirectory FROM Artifact.Windows.Sys.Users()

-- Parse username from path (Windows)
parse_string_with_regex(regex="\\\\Users\\\\(?P<User>[^\\\\]+)", string=OSPath).User

-- Parse username from path (macOS)
parse_string_with_regex(regex="/Users/(?P<User>[^/]+)", string=OSPath).User

-- Use pathspec for NTFS raw access
LET RootPath <= pathspec(Path=Root, accessor='ntfs')

sources:
  - name: Step1
    query: |
      LET X <= SELECT ...  -- X is visible to Step2
      SELECT * FROM ...
  - name: Step2
    query: |
      SELECT * FROM X     -- Can reference Step1's variables

sources:
  - name: WindowsData
    precondition: SELECT OS FROM info() WHERE OS = 'windows'
    query: |
      LET X <= ...  -- X is NOT visible to MacOSData
      SELECT * FROM ...
  - name: MacOSData
    precondition: SELECT OS FROM info() WHERE OS = 'darwin'
    query: |
      -- Cannot reference X from WindowsData
      SELECT * FROM ...

export: |
  LET CommonGlob <= glob(globs=PathGlob, accessor='auto')
  LET CommonFilter <= ... 

sources:
  - name: Source1
    query: |
      SELECT * FROM CommonFilter WHERE ...
  - name: Source2
    query: |
      SELECT * FROM CommonFilter WHERE ...

imports:
  - Custom.AIToolEvidence

name: Custom.AIToolEvidence
description: |
  Collects forensic evidence of AI tool usage across Windows, Linux, and macOS.
  
  Gathers configuration files, conversation logs, session data, and cache
  from AI coding assistants and chat tools.

type: CLIENT

export: |
  LET AIToolPaths <= SELECT * FROM glob(globs=SearchGlob, accessor='auto')
    WHERE NOT IsDir AND log(message="Found: " + OSPath)

parameters:
  - name: SearchGlob
    description: Glob pattern for AI tool files
    default: ...
  - name: UploadFiles
    type: bool
    default: Y
    description: Upload file content in addition to metadata

sources:
  - name: WindowsConfig
    precondition: SELECT OS FROM info() WHERE OS = 'windows'
    query: |
      ...

  - name: LinuxConfig
    precondition: SELECT OS FROM info() WHERE OS = 'linux'
    query: |
      ...

  - name: MacOSConfig
    precondition: SELECT OS FROM info() WHERE OS = 'darwin'
    query: |
      ...

  - name: ConversationLogs
    query: |
      SELECT OSPath, Size, Mtime, Modified,
             if(condition=UploadFiles,
                then=upload(file=OSPath)) AS Upload
      FROM AIToolPaths
      WHERE OSPath =~ 'conversation|history|chat|session'

column_types:
  - name: Mtime
    type: timestamp
  - name: Upload
    type: preview_upload

parameters:
  - name: ParameterName          # Required - variable name in VQL
    friendly_name: Display Name  # Optional - shown in GUI
    description: Help text       # Optional - tooltip/description
    default: default_value       # Always a string, even for numbers
    type: string                 # Data type (see below)
    validating_regex: '^...$'   # Visual validation hint only
    choices:                     # For choices/multichoice types
      - OptionA
      - OptionB

parameters:
  - name: MaxFiles
    type: int
    default: "100"
    validating_regex: '^\d{1,5}$'

LET MaxFiles <= if(condition=NOT MaxFiles =~ '^\d{1,5}$',
                   then=100,
                   else=int(int=MaxFiles))

reports:
  - type: CLIENT
    template: |
      {{ define "pre" }}
      LET Cap(X) = upcase(string=X[0:1]) + X[1:]
      {{ end }}
      {{ $_ := Query "pre" | Expand }}

      # Results for {{ Scope "Hostname" }}
      {{ Query "SELECT * FROM source(source='BasicInformation')" | Table }}

column_types:
  - name: Timestamp
    type: timestamp
  - name: Upload
    type: preview_upload
  - name: ChildrenTree
    type: tree