verosint

verosint

verosint is an open source tool that enables command line access to Verosint identity security endpoints.

Installation

Use the verosint tool to:

• Lookup account's and find identifiers, signals, fraud labels, and related accounts
• Send events to the SignalPrint endpoint to create a map of identities and access history.
• Generate an LDAP Schema file to store 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

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/verosint/public/verosint@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/verosint/public/verosint

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/verosint/public/verosint

Updating the tool

Use verosint update --check to see if newer version is available.

⚠ Due to hosting changes, updating from versions prior to 0.2.32 is not supported and requires reinstallation.

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 evaluate rule phone:15123944240 --ruleSetUuid 4f5ab21b-984c-455e-b889-b6b0272a4567

Account IDs

When using commands involving an account ID you should wrap the identifier in double quotes:

verosint signalprint lookup "babsjensen"

Evaluating Rules

Single Set of Identifiers

The CLI accepts the following identifiers.

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 evalute rule ip:2607:fb91:1296:c7dc:a0c4:25a9:ac7a:4384 email:user@example.com phone:15123944240 --ruleSetUuid 4f5ab21b-984c-455e-b889-b6b0272a4567

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 --ruleSetFile 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 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.

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 rules. An IP address, a user agent, and an event type are required for each event. You can optionally submit an event timestamp, an account identifier, an email address, and a phone number as well.

The timestamp is expected to be in the RFC3339 format. For example: 2019-01-22T03:56:17+03:30.

The type must be one of:

• ACCOUNT_RECOVERY_SUCCESS
• CHANGE_EMAIL_FAILED
• CHANGE_EMAIL_SUCCESS
• CHANGE_PASSWORD_FAILED
• CHANGE_PASSWORD_SUCCESS
• CHANGE_PHONE_FAILED
• CHANGE_PHONE_SUCCESS
• CHANGE_USERNAME_FAILED
• CHANGE_USERNAME_SUCCESS
• EMAILED
• LOGIN_FAILED
• LOGIN_SUCCESS
• LOGOUT_FAILED
• LOGOUT_SUCCESS
• MFA_DEVICE_UNENROLLED
• MFA_ENROLLMENT_FAILED
• MFA_ENROLLMENT_SUCCESS
• MFA_FAILED
• MFA_SUCCESS
• PUSH_NOTIFICATION_FAILED
• PUSH_NOTIFICATION_SUCCESS
• SIGNUP_FAILED
• SIGNUP_SUCCESS
• SMS_SEND_FAILED
• SMS_SEND_SUCCESS

Using the following event information saved in events.csv,

timestamp,ip,accountId,email,phone,userAgent,type
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",LOGIN_SUCCESS

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 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.21 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