@take2identity/verosint 0.2.4

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2023 Take 2 Identity, Inc <support@verosint.com> (https://verosint.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,322 @@
+# verosint
+
+![verosint](https://gitlab.com/443id/public/verosint/-/raw/main/assets/Verosint-logo-h-color.svg)
+[![Go Report Card][reportcard]](https://goreportcard.com/report/gitlab.com/443id/public/verosint)
+
+`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](https://en.wikipedia.org/wiki/Comma-separated_values),
+[LDIF](https://www.rfc-editor.org/rfc/rfc2849.html) files.
+* Send events to the SignalPrint endpoint to create a map of identities and access history.
+* Generate an [LDAP Schema](https://www.rfc-editor.org/rfc/rfc4512#page-22)
+file to store risk scoring and/or rules evaluation atttributes in user
+entries.
+
+Download the binary from:
+[releases page](https://gitlab.com/443id/public/verosint/-/releases).
+Binaries for macOS, Windows, and Linux are available.
+
+### Alternative Installation methods
+
+#### Node Package Manager (NPM)
+
+```shell
+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`
+
+```shell
+go install gitlab.com/443id/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.
+
+```shell
+docker run --rm registry.gitlab.com/443id/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:
+
+```shell
+docker run --rm -v "$HOME/.verosint.yaml:/root/.verosint.yaml" registry.gitlab.com/443id/public/verosint
+```
+
+## 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:
+
+```shell
+verosint --help
+```
+
+Note that each subcommand has its own specific help. For example, to
+print the help for the `evaluate rules-batch` subcommand, run:
+
+```shell
+verosint evaluate rules-batch --help
+```
+
+### Configuration File
+
+The tool can read settings from a configuration file in a
+[YAML](https://yaml.org/) 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:
+
+```yaml
+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:
+
+```shell
+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 | Email address |
+| phone | Phone number in the [international phone number format](https://en.wikipedia.org/wiki/E.164) |
+
+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](https://www.rfc-editor.org/rfc/rfc5952).
+
+Responses are provided in the JSON format on the standard output.
+
+##### Examples
+
+###### 1. Evaluate an IPv4 address for risk
+
+```shell
+verosint evaluate risk ip:172.66.43.186
+```
+
+###### 2. Evaluate an IPv6 address, a phone number and an email address for risk
+
+```shell
+verosint evaluate risk ip:2607:fb91:1296:c7dc:a0c4:25a9:ac7a:4384 email:user@example.com 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](https://app.verosint.com/rules) configuration and copy the UUID of
+the rule set you would like to evaluate.
+
+![Copy Rule Set UUID](assets/copyrulesetuuid.png)
+
+```shell
+verosint 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](https://app.verosint.com/rules)
+configuration into a local file as shown below.
+
+![Export Rule Set](assets/exportruleset.png)
+
+This example evaluates the `babs@jensen.com` email address against the rule defined
+in the `mfarule.json` file.
+
+```shell
+verosint evaluate rule email:babs@jensen.com --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](https://en.wikipedia.org/wiki/Geo-fence)
+purposes:
+
+```yaml
+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:
+
+```shell
+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.
+
+##### 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:
+
+```csv
+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:
+
+```shell
+verosint 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`.
+
+```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:
+
+```shell
+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](https://www.rfc-editor.org/rfc/rfc3339) format. For example:
+`2019-01-22T03:56:17+03:30`.
+
+##### Examples for Signal Print
+
+Using the following event information saved in `events.csv`,
+
+```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:
+
+```csv
+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](https://www.iana.org/assignments/enterprise-numbers/).
+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:
+
+```shell
+verosint generate schema
+```
+
+## Development
+
+## Prerequisites
+
+### Go
+
+Install the 1.20 version of [Go](https://golang.dev).
+
+### Task
+
+The [task](https://taskfile.dev/installation/) 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](mailto:support@verosint.com)
+
+[reportcard]: https://goreportcard.com/badge/gitlab.com/443id/public/verosint

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@take2identity/verosint",
+  "version": "0.2.4",
+  "description": "Official CLI to interact with Verosint API",
+  "main": "index.js",
+  "scripts": {
+    "postinstall": "node postinstall.js install",
+    "preuninstall": "node postinstall.js uninstall"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://gitlab.com/443id/public/verosint.git"
+  },
+  "author": "Verosint",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://gitlab.com/443id/public/verosint/-/issues"
+  },
+  "goBinary": {
+    "name": "verosint",
+    "path": "./bin",
+    "url": "https://gitlab.com/443id/public/verosint/-/releases/v{{version}}/downloads/verosint_"
+  },
+  "files": [
+    "dist",
+    "postinstall.js"
+  ],
+  "homepage": "https://gitlab.com/443id/public/verosint#readme",
+  "dependencies": {
+    "mkdirp": "^2.1.5",
+    "request": "^2.88.2",
+    "tar": "^6.1.13",
+    "unzipper": "0.10.11"
+  }
+}

package/postinstall.js

@@ -0,0 +1,280 @@
+#!/usr/bin/env node
+/*
+Copyright (c) 2023 Take 2 Identity, Inc
+*/
+"use strict"
+
+const { join } = require('path');
+const { exec } = require('child_process');
+const { existsSync, chmodSync, copyFileSync, unlinkSync, createWriteStream, readFileSync } = require('fs');
+const mkdirp = require('mkdirp');
+const request = require('request');
+const tar = require('tar');
+const zlib = require('zlib');
+const unzipper = require('unzipper');
+
+// Mapping from Node's `process.arch` to Our binary arch standard
+const ARCH_MAPPING = {
+    "x64": "x86_64",
+    "x32": "i386",
+    "arm64": "arm64",
+    "amd64": "x86_64"
+};
+
+// Mapping between Node's `process.platform` to Our binary platform standard
+const PLATFORM_MAPPING = {
+    "darwin": "MacOS",
+    "linux": "Linux",
+    "win32": "Windows",
+};
+
+function getInstallationPath(callback) {
+
+    // `npm bin` will output the path where binary files should be installed
+    exec('npm bin', (err, stdout, stderr) => {
+      let dir = null;
+      if (err || stderr || !stdout || stdout.length === 0) {
+  
+        // We couldn't infer path from `npm bin`. Let's try to get it from
+        // Environment variables set by NPM when it runs.
+        // npm_config_prefix points to NPM's installation directory where `bin` folder is available
+        // Ex: /Users/foo/.nvm/versions/node/v4.3.0
+        const env = process.env;
+  
+        if (env && env.npm_config_prefix) {
+          dir = join(env.npm_config_prefix, 'bin');
+        } else {
+          return callback(new Error('Error finding binary installation directory'));
+        }
+      } else {
+        dir = stdout.trim();
+      }
+  
+      dir = dir.replace(/node_modules.*[\/\\]\.bin/, join('node_modules', '.bin'));
+      mkdirp.sync(dir);
+      callback(null, dir);
+    });
+}
+
+function verifyAndPlaceBinary(binName, binPath, callback) {
+    if (!existsSync(join(binPath, binName))) {
+      return callback(`Downloaded binary does not contain the binary specified in configuration - ${binName}`);
+    }
+  
+    getInstallationPath((err, installationPath) => {
+        if (err) {
+          return callback(err);
+        }
+  
+        // Move the binary file and make sure it is executable
+        copyFileSync(join(binPath, binName), join(installationPath, binName));
+        unlinkSync(join(binPath, binName));
+        chmodSync(join(installationPath, binName), '755');
+  
+        console.log('Placed binary on', join(installationPath, binName));
+  
+        callback(null);
+    });
+}
+
+function validateConfiguration(packageJson) {
+
+    if (!packageJson.version) {
+        return "'version' property must be specified";
+    }
+
+    if (!packageJson.goBinary || typeof(packageJson.goBinary) !== "object") {
+        return "'goBinary' property must be defined and be an object";
+    }
+
+    if (!packageJson.goBinary.name) {
+        return "'name' property is necessary";
+    }
+
+    if (!packageJson.goBinary.path) {
+        return "'path' property is necessary";
+    }
+
+    if (!packageJson.goBinary.url) {
+        return "'url' property is required";
+    }
+}
+
+function parsePackageJson() {
+    if (!(process.arch in ARCH_MAPPING)) {
+        console.error("Installation is not supported for this architecture: " + process.arch);
+        return;
+    }
+
+    if (!(process.platform in PLATFORM_MAPPING)) {
+        console.error("Installation is not supported for this platform: " + process.platform);
+        return
+    }
+
+    const packageJsonPath = join(".", "package.json");
+    if (!existsSync(packageJsonPath)) {
+        console.error("Unable to find package.json. " +
+            "Please run this script at root of the package you want to be installed");
+        return
+    }
+
+    let packageJson = JSON.parse(readFileSync(packageJsonPath));
+    let error = validateConfiguration(packageJson);
+    if (error && error.length > 0) {
+        console.error("Invalid package.json: " + error);
+        return
+    }
+
+    // We have validated the config. It exists in all its glory
+    let binName = packageJson.goBinary.name;
+    let binPath = packageJson.goBinary.path;
+    let url = packageJson.goBinary.url;
+    let version = packageJson.version;
+
+    // Binary name on Windows has .exe suffix
+    if (process.platform === "win32") {
+        binName += ".exe";
+        url = url.replace(/{{win_ext}}/g, '.exe');
+    } else {
+        url = url.replace(/{{win_ext}}/g, '');
+    }
+
+    url = url.replace(/{{version}}/g, version);
+
+    switch(PLATFORM_MAPPING[process.platform]) {
+        case "MacOS":
+            url = url + "MacOS_all.tar.gz";
+            break;
+        case "Linux":
+            url = url + "Linux_" + ARCH_MAPPING[process.arch] + ".tar.gz";
+            break;
+        case "Windows":
+            url = url + "Windows_" + ARCH_MAPPING[process.arch] + ".zip";
+            break;
+        default:
+            console.error(`You have an unsupported platform (${process.platform}) or architecture (${process.arch})`);
+            return;
+    }
+
+    return {
+        binName: binName,
+        binPath: binPath,
+        url: url,
+        version: version
+    }
+}
+
+function unzip({ opts, req, onSuccess, onError }) {
+    const unzip = unzipper.Extract({ path: opts.binPath });
+    unzip.on('error', onError);
+    unzip.on('close', onSuccess);
+    req.pipe(unzip);
+}
+
+function untar({ opts, req, onSuccess, onError }) {
+    const ungz = zlib.createGunzip();
+    const untar = tar.Extract({ path: opts.binPath });
+    ungz.on('error', onError);
+    untar.on('error', onError);
+    untar.on('end', onSuccess);
+    req.pipe(ungz).pipe(untar);
+}
+
+/**
+ * Move strategy for binary resources without compression.
+ */
+function move({ opts, req, onSuccess, onError }) {
+    const stream = createWriteStream(join(opts.binPath, opts.binName));
+    stream.on('error', onError);
+    stream.on('close', onSuccess);
+    req.pipe(stream);
+}
+
+function getStrategy({ url }) {
+    if (url.endsWith('.tar.gz')) {
+        return untar;
+    } else if (url.endsWith('.zip')) {
+        return unzip;
+    } else {
+        return move;
+    }
+}
+
+/**
+ * Reads the configuration from application's package.json,
+ * validates properties, downloads the binary, untars, and stores at
+ * ./bin in the package's root. NPM already has support to install binary files
+ * specific locations when invoked with "npm install -g"
+ *
+ *  See: https://docs.npmjs.com/files/package.json#bin
+ */
+
+function install(callback) {
+
+    const opts = parsePackageJson();
+    if (!opts) return callback('Invalid inputs');
+  
+    mkdirp.sync(opts.binPath);
+  
+    console.log('Downloading from URL: ' + opts.url);
+
+    const req = request({ uri: opts.url });
+    req.on('error', () => callback('Error downloading from URL: ' + opts.url));
+    req.on('response', (res) => {
+        if (res.statusCode !== 200) return callback('Error downloading binary. HTTP Status Code: ' + res.statusCode);
+  
+        const strategy = getStrategy(opts);
+  
+        strategy({
+            opts,
+            req,
+            onSuccess: () => verifyAndPlaceBinary(opts.binName, opts.binPath, callback),
+            onError: callback
+        });
+    });
+}
+  
+
+function uninstall(callback) {
+    const { binName } = parsePackageJson();
+    getInstallationPath((err, installationPath) => {
+        if (err) {
+            return callback(err);
+        }
+        try {
+            unlinkSync(join(installationPath, binName));
+        } catch(ex) {
+            // Ignore errors when deleting the file.
+        }
+        return callback(null);
+    });
+}
+  
+
+
+// Parse command line arguments and call the right method
+let actions = {
+    "install": install,
+    "uninstall": uninstall
+};
+
+let argv = process.argv;
+if (argv && argv.length > 2) {
+    let cmd = process.argv[2];
+    if (!actions[cmd]) {
+        console.log("Invalid command to postinstall script. `install` and `uninstall` are the only supported commands");
+        process.exit(1);
+    }
+
+    actions[cmd](function(err) {
+        if (err) {
+            console.error(err);
+            process.exit(1);
+        } else {
+            process.exit(0);
+        }
+    });
+} else {
+    console.log('No command supplied. `install` and `uninstall` are the only supported commands');
+    exit(1);
+}