diff --git a/.wordlist.txt b/.wordlist.txt index 90b4ed5d78a..6f2b1585e6c 100644 --- a/.wordlist.txt +++ b/.wordlist.txt @@ -1374,6 +1374,7 @@ tgz KMS kmsencryptionkey uploadroot +credentialstoken # content/blog/2023/2023-07-27-release-notes-0.7.0/index.md SQLiteHunter @@ -1448,3 +1449,11 @@ Winget autoupdate denylist winget + +# content/vql_reference/misc/xattr/_index.md +xattr + + +# content/vql_reference/basic/humanize/_index.md +MiB +ibytes \ No newline at end of file diff --git a/content/vql_reference/basic/copy/_index.md b/content/vql_reference/basic/copy/_index.md index 92288661317..28028f36dfb 100644 --- a/content/vql_reference/basic/copy/_index.md +++ b/content/vql_reference/basic/copy/_index.md @@ -24,6 +24,7 @@ accessor|The accessor to use|string dest|The destination file to write.|string (required) permissions|Required permissions (e.g. 'x').|string append|If true we append to the target file otherwise truncate it|bool +create_directories|If true we ensure the destination directories exist|bool Required Permissions: FILESYSTEM_WRITE diff --git a/content/vql_reference/basic/humanize/_index.md b/content/vql_reference/basic/humanize/_index.md index 945ed0db2bd..5554b481aaf 100644 --- a/content/vql_reference/basic/humanize/_index.md +++ b/content/vql_reference/basic/humanize/_index.md @@ -19,7 +19,10 @@ no_edit: true Arg | Description | Type ----|-------------|----- -bytes|Format bytes with units|int64 +bytes|Format bytes with units (e.g. MB)|int64 +ibytes|Format bytes with units (e.g. MiB)|int64 +time|Format time (e.g. 2 hours ago)|time.Time +comma|Format integer with comma (e.g. 1,230)|int64 ### Description diff --git a/content/vql_reference/event/watch_etw/_index.md b/content/vql_reference/event/watch_etw/_index.md index b36b4317d60..10afc670571 100644 --- a/content/vql_reference/event/watch_etw/_index.md +++ b/content/vql_reference/event/watch_etw/_index.md @@ -26,8 +26,6 @@ all|All Keywords |uint64 level|Log level (0-5)|int64 stop|If provided we stop watching automatically when this lambda returns true|Lambda timeout|If provided we stop after this much time|uint64 -capture_state|If true, capture the state of the provider when the event is triggered|bool -enable_map_info|Resolving MapInfo with TdhGetEventMapInformation is very expensive and causes events to be dropped so we disabled it by default. Enable with this flag.|bool ### Description diff --git a/content/vql_reference/misc/_index.md b/content/vql_reference/misc/_index.md index 7c141d3ab29..1479d512fd3 100644 --- a/content/vql_reference/misc/_index.md +++ b/content/vql_reference/misc/_index.md @@ -74,3 +74,4 @@ Miscellaneous plugins not yet categorized. |[vfs_ls](vfs_ls)|Plugin|List directory and build a VFS object| |[write_crypto_file](write_crypto_file)|Plugin|Write a query into an encrypted local storage file| |[write_jsonl](write_jsonl)|Plugin|Write a query into a JSONL file| +|[xattr](xattr)|Function|Query a file for the specified extended attribute| diff --git a/content/vql_reference/misc/artifact_set_metadata/_index.md b/content/vql_reference/misc/artifact_set_metadata/_index.md index 0eb90d36bdb..9136d571578 100644 --- a/content/vql_reference/misc/artifact_set_metadata/_index.md +++ b/content/vql_reference/misc/artifact_set_metadata/_index.md @@ -30,3 +30,22 @@ Required Permissions: Sets metadata about the artifact. +This VQL function is used to clean up the artifact search screen +and guide users to assist with investigations. + +Velociraptor comes with a lot of built in artifacts which may be +confusing to some users and in specialized deployments it may be +preferable to guide users into a small subset of artifacts and +hide the rest. + +For example, say you have a set of custom artifacts that you only +want to show. Then I would add a special keyword to their +description (for example a company name - say "Written by ACME +inc"). Then a query like this will hide the others: + +```vql +SELECT name, artifact_set_metadata(name=name, hidden=TRUE) +FROM artifact_definitions() WHERE NOT description =~ "ACME" +``` + + diff --git a/content/vql_reference/misc/xattr/_index.md b/content/vql_reference/misc/xattr/_index.md new file mode 100644 index 00000000000..82fe908ccda --- /dev/null +++ b/content/vql_reference/misc/xattr/_index.md @@ -0,0 +1,41 @@ +--- +title: xattr +index: true +noTitle: true +no_edit: true +--- + + + +
+ + +## xattr +Function + + + +
+ +Arg | Description | Type +----|-------------|----- +filename|Filename to inspect.|OSPath (required) +attribute|Attribute to collect. |list of string +accessor|File accessor|string + +Required Permissions: +FILESYSTEM_READ + +### Description + +Query a file for the specified extended attribute. + +If no attributes are provided, this function will return all extended attributes +for the file. + +Please note: this API is not reliable, so please provided extended attributes +where possible. + +Note: This function only works on Mac and Linux. + + diff --git a/content/vql_reference/plugin/upload_s3/_index.md b/content/vql_reference/plugin/upload_s3/_index.md index e7d0e561f22..bcdcbaf40fb 100644 --- a/content/vql_reference/plugin/upload_s3/_index.md +++ b/content/vql_reference/plugin/upload_s3/_index.md @@ -26,6 +26,7 @@ bucket|The bucket to upload to|string (required) region|The region the bucket is in|string (required) credentialskey|The AWS key credentials to use|string credentialssecret|The AWS secret credentials to use|string +credentialstoken|The AWS session token to use (only needed for temporary credentials)|string endpoint|The Endpoint to use|string serversideencryption|The server side encryption method to use|string kmsencryptionkey|The server side KMS key to use|string diff --git a/content/vql_reference/server/elastic_upload/_index.md b/content/vql_reference/server/elastic_upload/_index.md index 0241213af82..7542cfbd349 100644 --- a/content/vql_reference/server/elastic_upload/_index.md +++ b/content/vql_reference/server/elastic_upload/_index.md @@ -35,6 +35,7 @@ disable_ssl_security|Disable ssl certificate verifications (deprecated in favor skip_verify|Disable ssl certificate verifications.|bool root_ca|As a better alternative to disable_ssl_security, allows root ca certs to be added here.|string max_memory_buffer|How large we allow the memory buffer to grow to while we are trying to contact the Elastic server (default 100mb).|uint64 +action|Either index or create. For data streams this must be create.|string Required Permissions: COLLECT_SERVER diff --git a/content/vql_reference/server/monitoring/_index.md b/content/vql_reference/server/monitoring/_index.md index ecf851fcb5e..7a9e605f4fc 100644 --- a/content/vql_reference/server/monitoring/_index.md +++ b/content/vql_reference/server/monitoring/_index.md @@ -28,6 +28,7 @@ start_time|Start return events from this date (for event sources)|Any end_time|Stop end events reach this time (event sources).|Any notebook_id|The notebook to read from (should also include cell id)|string notebook_cell_id|The notebook cell read from (should also include notebook id)|string +notebook_cell_version|The notebook cell version to read from (should also include notebook id and notebook cell)|string notebook_cell_table|A notebook cell can have multiple tables.)|int64 start_row|Start reading the result set from this row|int64 count|Maximum number of clients to fetch (default unlimited)'|int64 diff --git a/content/vql_reference/server/source/_index.md b/content/vql_reference/server/source/_index.md index 7d3eb72d21a..a465bad6b60 100644 --- a/content/vql_reference/server/source/_index.md +++ b/content/vql_reference/server/source/_index.md @@ -28,6 +28,7 @@ start_time|Start return events from this date (for event sources)|Any end_time|Stop end events reach this time (event sources).|Any notebook_id|The notebook to read from (should also include cell id)|string notebook_cell_id|The notebook cell read from (should also include notebook id)|string +notebook_cell_version|The notebook cell version to read from (should also include notebook id and notebook cell)|string notebook_cell_table|A notebook cell can have multiple tables.)|int64 start_row|Start reading the result set from this row|int64 count|Maximum number of clients to fetch (default unlimited)'|int64 diff --git a/static/reference/data.json b/static/reference/data.json index 3aefe14becf..a722e3d1663 100644 --- a/static/reference/data.json +++ b/static/reference/data.json @@ -937,6 +937,11 @@ "name": "append", "type": "bool", "description": "If true we append to the target file otherwise truncate it" + }, + { + "name": "create_directories", + "type": "bool", + "description": "If true we ensure the destination directories exist" } ], "category": "basic", @@ -1355,6 +1360,11 @@ "name": "max_memory_buffer", "type": "uint64", "description": "How large we allow the memory buffer to grow to while we are trying to contact the Elastic server (default 100mb)." + }, + { + "name": "action", + "type": "string", + "description": "Either index or create. For data streams this must be create." } ], "category": "server", @@ -2265,7 +2275,22 @@ { "name": "bytes", "type": "int64", - "description": "Format bytes with units" + "description": "Format bytes with units (e.g. MB)" + }, + { + "name": "ibytes", + "type": "int64", + "description": "Format bytes with units (e.g. MiB)" + }, + { + "name": "time", + "type": "time.Time", + "description": "Format time (e.g. 2 hours ago)" + }, + { + "name": "comma", + "type": "int64", + "description": "Format integer with comma (e.g. 1,230)" } ], "category": "basic" @@ -3515,6 +3540,11 @@ "type": "string", "description": "The notebook cell read from (should also include notebook id)" }, + { + "name": "notebook_cell_version", + "type": "string", + "description": "The notebook cell version to read from (should also include notebook id and notebook cell)" + }, { "name": "notebook_cell_table", "type": "int64", @@ -5922,6 +5952,11 @@ "type": "string", "description": "The notebook cell read from (should also include notebook id)" }, + { + "name": "notebook_cell_version", + "type": "string", + "description": "The notebook cell version to read from (should also include notebook id and notebook cell)" + }, { "name": "notebook_cell_table", "type": "int64", @@ -6858,6 +6893,11 @@ "type": "string", "description": "The AWS secret credentials to use" }, + { + "name": "credentialstoken", + "type": "string", + "description": "The AWS session token to use (only needed for temporary credentials)" + }, { "name": "endpoint", "type": "string", @@ -7689,6 +7729,33 @@ "permissions": "FILESYSTEM_WRITE" } }, + { + "name": "xattr", + "description": "Query a file for the specified extended attribute.", + "type": "Function", + "args": [ + { + "name": "filename", + "type": "OSPath", + "description": "Filename to inspect.", + "required": true + }, + { + "name": "attribute", + "type": "string", + "description": "Attribute to collect. ", + "repeated": true + }, + { + "name": "accessor", + "type": "string", + "description": "File accessor" + } + ], + "metadata": { + "permissions": "FILESYSTEM_READ" + } + }, { "name": "xor", "description": "Apply xor to the string and key.",