Extended Search Capabilities

Created by Xinxiang Wang, Modified on Fri, 15 Dec, 2023 at 8:23 AM by Xinxiang Wang

To verify if your license is extended with regards to search, check the
License Management screen which is available in the top right corner:

If your license is extended with search capabilities, you should see the
following line:

With extended search the list of available fields to search in is the
following:

Available fields

field	description	examples
attachment_filenames	list of attached filenames	has_attachment:*, has_attachment:file.json
attachment_labels	labels provided for attachment during notarization	attachment_labels:*
content_type	type of the content in the artifact, examples below the table	content_type:application*
file_size	file size in bytes	file_size:[100 TO 150]
hash	hash from notarization	hash:652fc2bfeaf00b7af*
has_attachment	filters artifacts with attachments	has_attachment:*
has_sbom	filters artifacts with SBOM	has_sbom:*
includes	finds the artifacts that in their SBOM contain another artifact of a specified name	includes:bonjour
kind	type of the document, examples: container, dir, docker, dpkg, file, git, go, image, java, node, php, python, rust etc.	kind:git
labels	list of labels attached to artifact (eg. the —-labels-add option in `vcn`)	labels:flat-file
ledger_name	ledger name	ledger_name:test
license	license of software or component	license:MIT
metadata	metadata populated by `vcn` (eg. in case of image) or by user through the —-attr option in `vcn`. Keys and values are processed separately	metadata:purl, metadata:ncurses*
name	name of the artifact notarized	name:vcn-enterprise
notarized_time	the timestamp of notarization. It is possible to use NOW	notarized_time:[NOW-1DAY TO NOW], notarized_time:["2022-08-15T09:11:25.887Z" TO "2022-12-16T09:11:25.887Z"]
signer_id	signer_id who does the notarization in `vcn` with his/her api-key	signer_id:joe
status	possible values: “trusted”, “untrusted”, “unsupported”	status:untrusted
updated_time	timestamp of last update (often the same as notarization time)	like notarized_time
version	version of the notarized artifact	version:1.0.0

Examples for the content_type field: "text/plain; charset=utf-8",
"application/x-executable", "application/x-tar", "application/json",
"application/vnd.microsoft.portable-executable".

Advanced syntax

file_size:0��2000TO200

File size in range inclusive.

Note: There are spaces before and after the "TO" keyword.

file_size:{121 TO 126}

File size in range exclusive.

file_size:ParseError: KaTeX parse error: Undefined control sequence: \* at position 8: 121 TO \̲*̲

File size equal or larger than 121.

-kind:"dir"

Artifact kind is other than "dir".

(ledger_name:test AND metadata:purl*) OR kind:php

Example using AND and OR in one search. Searches for artifacts that are
either in ledger test with metadata starting with purl or are PHP files.

Note: Keywords such as "AND", "OR", "TO" must be spelled using
capital letters.

Regular expressions

name:/�−�a−z{5}/

You can also search using some functionality of regular expressions. The
example searches for names that consist of five uncapitalized letters.

Note: Regular expressions must be enclosed by '/'.

name:/�−�a−z{1}.{3}0−90−9{2}/

Find artifacts that have a letter in beginning, any 3 characters and
ends with two digits.

name:/.*\d{5,10}.*/

The artifact name contains a string that is made of 5 to 10 consecutive
digits anywhere in it.

Note: When using the regular expressions it may take a little longer
for the results to appear.

Multivalue field (eg. metadata, labels)

metadata:(*)

Returns documents with a nonempty metadata field.

metadata:(system* AND *GIT)

In the strings set in metadata there is either a string beginning with
"system" or ending with "GIT".

-labels:ParseError: KaTeX parse error: Undefined control sequence: \* at position 1: \̲*̲ TO \*

Searches for documents where field "labels" does not exist (no labels
have been specified).

DateTime fields

It is preferable to conduct the search for DateTime (local time) using
the dedicated field (which filters results using the notarized time).
However, you can also include date and time conditions using syntax
similar to the following examples. Please be aware that both these
fields will be considered in parsing and returning the search results
conforming to conditions from both fields.

notarized_time:ParseError: KaTeX parse error: Expected group as argument to '\"' at position 29: …09:11:25.887Z\" ̲TO \"2022-08-16…

Searching in a declared time period in a typical timestamp format.

notarized_time:��−1��NOW−1DAYTONOW

Last 24 hours.

notarized_time:��−1��NOW−1MONTHTONOW

Last month.

notarized_time:��/��−1��/��NOW/HOUR−1DAYTONOW/HOUR

Period from yesterday at the beginning of the current hour to today at
the beginning of the current hour.