README ¶
verosint-cli
verosint
is an open source tool that enables command line access to Verosint identity security endpoints.
Installation
Use the verosint
tool to:
- Evaluate risk scores or create a rule set for a single set of identifiers (email, IP, and/or phone number).
- Determine risk by running a batch evaluation for identifiers using a CSV, LDIF files.
- Send events to the SignalPrint endpoint to create a map of identities and access history.
- Generate an LDAP Schema file to store risk scoring and/or rules evaluation atttributes in user entries.
Download the binary from: releases page. Binaries for macOS, Windows, and Linux are available.
Alternative Installation methods
Node Package Manager (NPM)
npm i -g @take2identity/verosint-cli
Check permissions before installing the CLI tool. If installation fails, run the command with "sudo" (MacOS/Linux), or run the command inside a terminal using administrator privileges (Windows).
Using go install
go install gitlab.com/443id/public/verosint-cli@latest
Executing with a Docker container
Use the following command to run the CLI inside a Docker container without having to install the tool on your system. This method also enables running the CLI inside in a containerized CI/CD pipeline.
docker run --rm registry.gitlab.com/443id/public/verosint-cli
Configuration for the CLI is stored in the .verosint.yaml
file in the
home directory. To make the configuration accessible to the Docker
container, create a volume map for the configuration file. For example:
docker run --rm -v "$HOME/.verosint.yaml:/root/.verosint.yaml" registry.gitlab.com/443id/public/verosint-cli
Usage
After installing the CLI, you can execute it using verosint
.
Interacting with the Verosint APIs require an API key. You can pass the API
key using the --apiKey
argument. It is recommended to store the API
key inside a configuration file or an environment variable to prevent
exposure.
You can get command help using the --help
argument:
verosint --help
Note that each subcommand has its own specific help. For example, to
print the help for the evaluate rules-batch
subcommand, run:
verosint evaluate rules-batch --help
Configuration File
The tool can read settings from a configuration file in a YAML format. For example, you can store the API key as well as rules inside the file.
By default, the tool looks for the configuration file .verosint.yaml
in
your home directory. You can override this setting with the
--configFile
flag.
An example configuration file:
apiKey: <API key goes here>
rules:
- name: IP - Tor/Bot/VPN
outcomes:
- DENY
query: 'signals.ip.bot || signals.ip.tor || signals.ip.vpn'
reason: This IP address is a known bot, active Tor node, or a VPN
API key as an Environment Variable
You can also set the VEROSINT_APIKEY
environment variable to hold the value
of the API key:
export VEROSINT_APIKEY="API key goes here"
verosint evaluate risk ip:172.66.43.186
Evaluating Risk or Rules
Single Set of Identifiers
The CLI accepts the following identifiers.
Name | Description |
---|---|
ip | IP address (either IPv4 or IPv6) |
Email address | |
phone | Phone number in the international phone number format |
When providing a set of identifiers, the API expects one or more identifiers (IP address, email, or phone number) and only one value per identifier.
IPv6 addresses may compress zeros for a shorter form and use representations as described in RFC 5952.
Responses are provided in the JSON format on the standard output.
verosint evaluate risk ip:172.66.43.186
verosint evaluate risk ip:2607:fb91:1296:c7dc:a0c4:25a9:ac7a:4384 email:user@example.com phone:15123944240
To obtain the UUID of the rule set, visit the Rules configuration and copy the UUID of the rule set you would like to evaluate.
verosint evalute rule ip:104.255.6.45 --ruleSetUuid 4f5ab21b-984c-455e-b889-b6b0272a4567
You can export a rule set defined in the Rules configuration into a local file as shown below.
This example evaluates the babs@jensen.com
email address against the rule defined
in the mfarule.json
file.
verosint evaluate rule email:babs@jensen.com --rulesSetFile mfarule.json
You can place rules inside a local configuration file. The following is
an example file that uses the isWithin
function, which enables you to
create rules for geo-fencing
purposes:
apiKey: <API key goes here>
rules:
- name: IP not in Austin
outcomes:
- DENY
query: '!signals.ip.geo.isWithin(30.3079827, -97.895826, 100)'
reason: This IP is not within 100 kilometers of Austin, Texas
The following example runs the same rule saved in the default
configuration file against the 104.16.44.99
IP address:
verosint evaluate rules ip:104.16.44.99
Batch Evaluation
Use input files to evaluate multiple sets of identifiers for risk or against rules. Batch commands can use input and output files in CSV or LDIF format, and can produce a report file formatted as JSON.
Processing time may take much longer with larger files, than for a single set of identifiers.
The input file does not have to be fully populated for all identifiers. For example, the following CSV-formatted input file is valid without a phone number present on the last record:
ip,email,phone
104.16.44.99,babs@jensen.com,15123944240
2607:fb91:1296:c7dc:a0c4:25a9:ac7a:4384,alison@example.com,
To evaluate the same file and save it as myRecords.csv
, run the
following command:
verosint evaluate risk-batch --inputFile myRecords.csv \
--outputFile riskOutput.csv --reportFile riskReport.json
If using an input file that has multiple identifiers, you can provide a
column index (where 0 refers to the first column) to indicate where the
value of a particular identifier is present. This content is saved in
mapped.csv
.
ipaddress,mail,telephone
104.16.44.99,babs@jensen.com,15123944240
Using the rules present in the default configuration file, the following command generates LDIF-formatted output and JSON report files:
verosint evaluate rules-batch ip:0 email:1 phone:2 \
--inputFile mapped.csv \
--outputFile output.ldif --outputType ldif \
--reportFile report.json
Submitting SignalPrint Events
You can submit events to the SignalPrint endpoint using the
signalprint send-events
subcommand. This subcommand works like the
batch commands for risk and rules. An event timestamp, IP address, and
user agent is required for each event. You can optionally add an
accountId, email, and/or phone with each event.
The timestamp is expected to be in the
RFC3339 format. For example:
2019-01-22T03:56:17+03:30
.
Using the following event information saved in events.csv
,
timestamp,ip,accountId,email,phone,userAgent
2019-01-22T03:56:17-05:00,104.16.44.99,babs_jensen,babs@jensen.com,15123944240,"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/109.0.0.0 Safari/537.36"
you can send the event to SignalPrint with:
verosint signalprint send-events --inputFile events.csv
Generating LDAP Schema
This command prints an LDAP schema that allows you to enrich existing user entries in your directory with risk or rule evaluation data from the API. The enterprise number (59592) in the object identifiers (OIDs) is registered with the Internet Assigned Numbers Authority. This guarantees that the schema will not collide with your existing schema elements.
Note that generating the LDAP schema does not require an API key. To generate a schema, run the following command:
verosint generate schema
Development
Prerequisites
Go
Install the 1.20 version of Go.
Task
The task utility is required to execute the various build related tasks.
Testing
Unit tests can be executed using the task test:unit
command. Our goal
is to maintain a minimum of 70% coverage.
Issues
Report issues at Verosint Support