443id-cli

Deprecation Notice

The 443id-cli has been deprecated due to naming changes and is replaced with the verosint. This repository is no longer maintained and may be removed in the future. The new tool is available from the Verosint CLI repository.

Users of the 443id-cli migrating to the new tool should note the following changes:

• The default configuration file name has changed to .verosint.yaml.
• The environment variable for holding the API key has changed from CLI_APIKEY to VEROSINT_APIKEY.

Original Content Prior to Deprecation

443id-cli is an open source tool that enables command line access to 443ID identity security endpoints.

Installation

Use the 443id-cli 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/443id-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/443id-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/443id-cli

Configuration for the CLI is stored in the .443id.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/.443id.yaml:/root/.443id.yaml" registry.gitlab.com/443id/public/443id-cli

Usage

After installing the CLI, you can execute it using 443id-cli.

Interacting with the 443ID 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:

443id-cli --help

Note that each subcommand has its own specific help. For example, to print the help for the evaluate rules-batch subcommand, run:

443id-cli 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 .443id.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 CLI_APIKEY environment variable to hold the value of the API key:

export CLI_APIKEY="API key goes here"
443id-cli 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 | 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.

Examples

1. Evaluate an IPv4 address for risk

443id-cli evaluate risk ip:172.66.43.186

2. Evaluate an IPv6 address, a phone number and an email address for risk

443id-cli evaluate risk ip:2607:fb91:1296:c7dc:a0c4:25a9:ac7a:4384 email:[email protected] phone:15123944240

3. Evaluate an IPv4 for address against a rule set already defined in the configuration

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.

443id-cli evalute rule ip:104.255.6.45 --ruleSetUuid 4f5ab21b-984c-455e-b889-b6b0272a4567

4. Evaluate an Email address against a rule set provided using a local file

You can export a rule set defined in the Rules configuration into a local file as shown below.

This example evaluates the [email protected] email address against the rule defined in the mfarule.json file.

443id-cli evaluate rule email:[email protected] --rulesSetFile mfarule.json

5. Check if an IP address is within 100 kilometers of Austin, TX using a local rule set

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:

443id-cli 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.

Batch Evaluation Examples

1. Executing Batch Risk Evaluation using CSV input/output format

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,[email protected],15123944240
2607:fb91:1296:c7dc:a0c4:25a9:ac7a:4384,[email protected],

To evaluate the same file and save it as myRecords.csv, run the following command:

443id-cli evaluate risk-batch --inputFile myRecords.csv \
  --outputFile riskOutput.csv --reportFile riskReport.json

2. Executing Batch Rules Evaluation with column index and LDIF output

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,[email protected],15123944240

Using the rules present in the default configuration file, the following command generates LDIF-formatted output and JSON report files:

443id-cli 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.

Examples for Signal Print

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,[email protected],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:

443id-cli 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:

443id-cli generate schema

Development

Prerequisites

Go

Install the 1.19 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 443ID Support