In the GUI, Artifacts are created, edited and managed on the View Artifacts screen. Here you can search and view all artifacts known to your server. The GUI also includes a feature-rich artifact editor, which you can access on this screen.
In order to create, modify or delete artifacts your user needs to have the
ARTIFACT_WRITER
permission.
Users with this permission are generally considered to be “admin equivalent” since it is easy to escalate to full admin be designing artifacts to accomplish that goal.
This permission is not needed to run artifacts, so it is common to have some users who can only run artifacts and some other users who can create and manage artifacts.
The search bar on the right side of the Artifacts screen allows you to search by any text string, regular expression, and certain category expressions (see table below).
As explained here
the name
,
aliases
, and description
fields from all artifacts are indexed and
searchable.
When searching, you can also limit the results using predefined Category Filters, which are available as a drop-down list next to the search bar.
Category Filter | Filter expression | Notes |
---|---|---|
Client Artifacts | type:CLIENT | |
Server Artifacts | type:SERVER | |
Notebook templates | type:NOTEBOOK | |
All Artifacts | <none> | Only includes artifacts with sources. |
Windows Only | precondition:WINDOWS | |
Linux Only | precondition:LINUX | |
macOS Only | precondition:DARWIN | |
Client Monitoring | type:CLIENT_EVENT | |
Server Monitoring | type:SERVER_EVENT | |
Using Tools | tool:.+ | |
Exchange | ^exchange.+ | |
BuiltIn Only | builtin:yes | |
Custom Only | builtin:no | |
Basic Only | metadata:basic | |
Include Empty sources | empty:true | Same as “All Artifacts” filter but also includes artifacts without sources.** |
** For more information about artifacts without sources see here .
The above filter expressions can also be used in the search bar directly and combined with search strings. Searches are not case-sensitive.
For example:
process type:client_event
will show all client event artifacts that also
(i.e. and is implied) have the word “process”.tool:sysmonbinary
will show all artifacts that use the tool named
“SysmonBinary”.There are many ways to add artifact definitions to Velociraptor. On the Artifacts screen you can import zip archives containing multiple artifacts.
When importing artifact packs you are given the option to add a custom prefix to
the artifact name (if you want a .
then you need to include it to your
prefix!), and the option to only import artifacts that match a name filter.
The file structure inside the zip doesn’t matter. Velociraptor will search for
all files in the zip with a .yaml
or .yml
file extension. The imported
artifacts will be saved to the server’s datastore using the file and folder
structure described
here
.
Velociraptor includes several server artifacts which can import additional artifacts from related external projects.
Project name | Project website | Import artifact |
---|---|---|
Velociraptor Artifact Exchange | https://docs.velociraptor.app/exchange/ | Server.Import.ArtifactExchange |
Curated Sigma Rules (Hayabusa/Hayabusa Live/ChopChopGo) | https://sigma.velocidex.com/ | Server.Import.CuratedSigma |
RegistryHunter | https://registry-hunter.velocidex.com/ | Server.Import.RegistryHunter |
Rapid7Labs | https://github.com/rapid7/Rapid7-Labs/tree/main/Vql | Server.Import.Rapid7Labs |
DetectRaptor | https://github.com/mgreen27/DetectRaptor | Server.Import.ArtifactExchange -> Server.Import.DetectRaptor |
KapeFiles or SQLiteHunter | https://github.com/EricZimmerman/KapeFiles https://github.com/Velocidex/SQLiteHunter | Server.Import.UpdatedBuiltin |
Artifacts from previous releases | https://github.com/Velocidex/velociraptor/releases | Server.Import.PreviousReleases |
The reason that the artifacts imported by the above are not included by default is that they are either rapidly developing and not synced to the Velociraptor release cycle, or are still considered experimental, or are community contributed. Some (probably RegistryHunter, SQLiteHunter and Curated Sigma Rules) may be included by default in future as these projects mature.
We also have a built-in server artifact which updates selected artifacts to their latest version, and another which imports all artifacts from a previous releases.
The purpose of the Server.Import.UpdatedBuiltin
artifact is to update either
of the following 2 artifacts which may be updated between releases:
Windows.KapeFiles.Targets
Generic.Forensic.SQLiteHunter
By default, this artifact will add the prefix Updated.
to the imported
artifact.
The Server.Import.PreviousReleases
artifact allows importing the artifacts
from older releases. This is to cater for situations where clients cannot be
easily upgraded, yet need functionality only found in the latest artifacts.
While clients should have no problems running older versions of the standard artifacts, we cannot guarantee that the latest artifact versions will be compatible with older clients. This depends mainly on whether or not the latest artifact versions contain VQL that uses new functions or plugins which the older client may not have. You should always test your particular scenario.
In the Artifacts page you can create a new artifact by clicking the Add Artifact () button in the artifacts toolbar.
This brings up the artifact editor, populated with a very basic boilerplate artifact to help get you started.
When you select an existing built-in artifact in the GUI, and then attempt to edit it, you are actually creating a custom copy of that artifact.
If the artifact is a compiled-in artifact then editing it will result in a
copy being created with the Custom.
prefix added to the name.
If the artifact is a built-in artifact then editing it will result in a copy but you’ll need to ensure that you choose a new name for it.
If the artifact is custom (that is, not built-in) then you can just edit it and save it, which will overwrite the previous version.
If you try to use the same name as an existing built-in artifact (or an existing alias) then you will receive an error message and the artifact will refuse to be saved.
You cannot delete built-in artifacts through the GUI either; the delete button is grayed out when they are selected.
The editor provides syntax highlighting for YAML and VQL. If you don’t like the default colors, you can choose a different theme in the editor’s preferences pane. These preferences are user-specific, that is, they are saved as preferences for your Velociraptor user.
There are many things that you can change in the editor’s settings but the most common items to tweak are the theme and font size.
The editor preferences you set here will also be used in other places in the GUI, for example notebooks which use the same editor component.
VQL doesn’t care about formatting, but for us humans it’s nice to have VQL code that is neat and legible. The Reformat VQL button will reformat the code in all VQL blocks. In general it wraps and aligns the VQL so that it can be easily read.
Note that this action applies to all VQL blocks in the artifact.
If you reformat the VQL and don’t like the result then you can use the
Crtl
+z
keyboard shortcut to revert the changes. You can also copy a section
of reformatted VQL that you do like, revert the changes, and then paste that
section over the original.
The artifact editor is based on the Ace code editor and therefore supports it’s extensive list of keyboard shortcuts, shown here: https://ace.c9.io/demo/keyboard_shortcuts.html
Many of these keyboard shortcuts are the same as in other code editors that you may already be familiar with.
The artifact editor offers suggestions and completions, as you type, for VQL keywords, functions and plugins, as well as their arguments.
The suggestions also include previously defined strings in the artifact such as parameter names and variable names. This helps you to avoid mistakes when typing the names of previously defined parameters and variables in your VQL, since you can simply select them from the suggestions list.
When you type ?
, or start typing a word, the editor presents a dropdown
list of suggestions.
Use your <Up>
and <Down>
arrow keys to select an item from the
suggestions list, and <Enter>
to complete it. You can also use your mouse
to hover over the suggestions list and select items, but using only your
keyboard is much faster.
For each item in the suggestions list it also includes the type of each item being suggested (keyword, function, plugin, local string).
For VQL functions and plugins the suggestions list also provides a preview of the help documentation for the function/plugins as you step through them (or hover over them with your mouse).
All artifacts created or imported during runtime, are created in the server’s datastore and can therefore be deleted.
This can be done:
artifact_delete
function, orServer.Import.DeleteArtifacts
.Artifacts loaded from these external sources are deemed “built-in” and cannot be deleted during runtime:
autoexec.artifact_definitions
sectionFrontend.artifact_definitions_directory
config settingdefaults.artifact_definitions_directories
config setting--definitions
CLI flagIf you need to delete such artifacts then you should manually remove the corresponding YAML documents from their source locations, and then restart the server.
For a more extensive discussion of built-in artifacts please see Built-in vs. Compiled-in vs. Custom Artifacts .