Code42 command-line interface (CLI)

https://img.shields.io/pypi/l/code42cli.svglicense https://img.shields.io/pypi/pyversions/code42cli.svgversions

The Code42 command-line interface (CLI) tool offers a way to interact with your Code42 environment without using the Code42 console or making API calls directly. For example, you can use it to extract Code42 data for use in a security information and event management (SIEM) tool or manage users on the High Risk Employees list or Departing Employees list.

Requirements

To use the Code42 CLI, you must have:

  • A Code42 product plan that supports the feature or functionality for your use case
  • Endpoint monitoring enabled in the Code42 console
  • Python version 3.6 and later installed

Content

User Guides

Get started with the Code42 command-line interface (CLI)

Licensing

This project uses the MIT License.

Installation

You can install the Code42 CLI from PyPI, from source, or from distribution.

From PyPI

The easiest and most common way is to use pip:

python3 -m pip install code42cli

To install a previous version of the Code42 CLI via pip, add the version number. For example, to install version 0.4.1, enter:

python3 -m pip install code42cli==0.5.3

Visit the project history on PyPI to see all published versions.

From source

Alternatively, you can install the Code42 CLI directly from source code:

git clone https://github.com/code42/code42cli.git

When it finishes downloading, from the root project directory, run:

python setup.py install
From distribution

If you want create a .tar ball for installing elsewhere, run the following command from the project’s root directory:

python setup.py sdist

After it finishes building, the .tar ball will be located in the newly created dist directory. To install it, enter:

python3 -m pip install code42cli-[VERSION].tar.gz
Updates

To update the CLI, use the pip --upgrade flag.

python3 -m pip install code42cli --upgrade
Authentication

Important

The Code42 CLI currently only supports token-based authentication.

To use the CLI, you must provide your credentials (basic authentication). If you choose not to store your password in the CLI, you must enter it for each command that requires a connection.

The Code42 CLI currently does not support SSO login providers or any other identity providers such as Active Directory or Okta.

Windows and Mac

For Windows and Mac systems, the CLI uses Keyring when storing passwords.

Red Hat Enterprise Linux

To use Keyring to store the credentials you enter in the Code42 CLI, enter the following commands before installing.

yum -y install python-pip python3 dbus-python gnome-keyring libsecret dbus-x11
pip3 install code42cli

If the following directories do not already exist, create them:

mkdir -p ~/.cache
mkdir -p ~/.local/share/keyring

In the following commands, replace the example value \n with the Keyring password (if the default Keyring already exists).

eval "$(dbus-launch --sh-syntax)"
eval "$(printf '\n' | gnome-keyring-daemon --unlock)"
eval "$(printf '\n' | /usr/bin/gnome-keyring-daemon --start)"

Close out your D-bus session and GNOME Keyring:

pkill gnome
pkill dbus

If you do not use Keyring to store your credentials, the Code42 CLI will ask permission to store your credentials in a local flat file with read/write permissions for only the operating system user who set the password. Alternatively, you can enter your password with each command you enter.

Ubuntu

If Keyring doesn’t support your Ubuntu system, the Code42 CLI will ask permission to store your credentials in a local flat file with read/write permissions for only the operating system user who set the password. Alternatively, you can enter your password with each command you enter.

To learn more about authenticating in the CLI, follow the Configure profile guide.

Troubleshooting and support
Debug mode

Debug mode may be useful if you are trying to determine if you are experiencing permissions issues. When debug mode is on, the CLI logs HTTP request data to the console. Use the -d flag to enable debug mode for a particular command. -d can appear anywhere in the command chain:

code42 <command> <subcommand> <args> -d
File an issue on GitHub

If you are experiencing an issue with the Code42 CLI, select New issue at the project repository to create an issue. See the Github guide on creating an issue for more information.

Contact Code42 Support

If you don’t have a GitHub account and are experiencing issues, contact Code42 support.

What’s next?

Learn how to Set up a profile.

Configure profile

Use the code42 profile set of commands to establish the Code42 environment you’re working within and your user information.

First, create your profile:

code42 profile create --name MY_FIRST_PROFILE --server example.authority.com --username security.admin@example.com

Your profile contains the necessary properties for authenticating with Code42. After running code42 profile create, the program prompts you about storing a password. If you agree, you are then prompted to enter your password.

Your password is not shown when you do code42 profile show. However, code42 profile show will confirm that a password exists for your profile. If you do not set a password, you will be securely prompted to enter a password each time you run a command.

You can add multiple profiles with different names and the change the default profile with the use command:

code42 profile use MY_SECOND_PROFILE

When you use the --profile flag with other commands, such as those in security-data, that profile is used instead of the default profile. For example,

code42 security-data search -b 2020-02-02 --profile MY_SECOND_PROFILE

To see all your profiles, do:

code42 profile list

Ingest file event data or alerts into a SIEM tool

This guide provides instructions on using the CLI to ingest Code42 file event data or alerts into a security information and event management (SIEM) tool like LogRhythm, Sumo Logic, or IBM QRadar.

Considerations

To ingest file events or alerts into a SIEM tool using the Code42 command-line interface, the Code42 user account running the integration must be assigned roles that provide the necessary permissions.

Before you begin

First install and configure the Code42 CLI following the instructions in Getting Started.

Run queries

You can get file events in either a JSON or CEF format for use by your SIEM tool. Alerts data is available in JSON format. You can query the data as a scheduled job or run ad-hoc queries. Learn more about searching using the CLI.

Run a query as a scheduled job

Use your favorite scheduling tool, such as cron or Windows Task Scheduler, to run a query on a regular basis. Specify the profile to use by including --profile. An example using the send-to command to forward only the new file event data since the previous request to an external syslog server:

code42 security-data send-to syslog.example.com:514 -p UDP --profile profile1 -c syslog_sender

An example to send to the syslog server only the new alerts that meet the filter criteria since the previous request:

code42 alerts send-to syslog.example.com:514 -p UDP --profile profile1 --rule-name “Source code exfiltration” --state OPEN -i

As a best practice, use a separate profile when executing a scheduled task. Using separate profiles can help prevent accidental updates to your stored checkpoints, for example, by adding --use-checkpoint to adhoc queries.

Run an ad-hoc query

Examples of ad-hoc queries you can run are as follows.

Print file events since March 5 for a user in raw JSON format:

code42 security-data search -f RAW-JSON -b 2020-03-05 --c42-username 'sean.cassidy@example.com'

Print file events since March 5 where a file was synced to a cloud service:

code42 security-data search -t  CloudStorage -b 2020-03-05

Write to a text file the file events in raw JSON format where a file was read by browser or other app for a user since March 5:

code42 security-data search -f RAW-JSON -b 2020-03-05 -t ApplicationRead --c42-username 'sean.cassidy@example.com' > /Users/sangita.maskey/Downloads/c42cli_output.txt

Print alerts since May 5 where a file’s cloud share permissions changed:

code42 alerts print -b 2020-05-05 --rule-type FedCloudSharePermissions

Example output for a single file exposure event (in default JSON format):

{
    "eventId": "0_c4b5e830-824a-40a3-a6d9-345664cfbb33_942704829036142720_944009394534374185_342",
    "eventType": "CREATED",
    "eventTimestamp": "2020-03-05T14:45:49.662Z",
    "insertionTimestamp": "2020-03-05T15:10:47.930Z",
    "filePath": "C:/Users/sean.cassidy/Google Drive/",
    "fileName": "1582938269_Longfellow_Cloud_Arch_Redesign.drawio",
    "fileType": "FILE",
    "fileCategory": "DOCUMENT",
    "fileSize": 6025,
    "fileOwner": "Administrators",
    "md5Checksum": "9ab754c9133afbf2f70d5fe64cde1110",
    "sha256Checksum": "8c6ba142065373ae5277ecf9f0f68ab8f9360f42a82eb1dec2e1816d93d6b1b7",
    "createTimestamp": "2020-03-05T14:29:33.455Z",
    "modifyTimestamp": "2020-02-29T01:04:31Z",
    "deviceUserName": "sean.cassidy@example.com",
    "osHostName": "LAPTOP-091",
    "domainName": "192.168.65.129",
    "publicIpAddress": "71.34.10.80",
    "privateIpAddresses": [
        "fe80:0:0:0:8d61:ec3f:9e32:2efc%eth2",
        "192.168.65.129",
        "0:0:0:0:0:0:0:1",
        "127.0.0.1"
    ],
    "deviceUid": "942704829036142720",
    "userUid": "887050325252344565",
    "source": "Endpoint",
    "exposure": [
        "CloudStorage"
    ],
    "syncDestination": "GoogleBackupAndSync"
}

Example output for a single alert (in default JSON format):

{"type$": "ALERT_DETAILS",
"tenantId": "c4b5e830-824a-40a3-a6d9-345664cfbb33",
"type": "FED_CLOUD_SHARE_PERMISSIONS",
"name": "Cloud Share",
"description": "Alert Rule for data exfiltration via Cloud Share",
"actor": "leland.stewart@example.com",
"target": "N/A",
"severity": "HIGH",
"ruleId": "408eb1ae-587e-421a-9444-f75d5399eacb",
"ruleSource": "Alerting",
"id": "7d936d0d-e783-4b24-817d-f19f625e0965",
"createdAt": "2020-05-22T09:47:33.8863230Z",
"state": "OPEN",
"observations": [{"type$": "OBSERVATION",
"id": "4bc378e6-bfbd-40f0-9572-6ed605ea9f6c",
"observedAt": "2020-05-22T09:40:00.0000000Z",
"type": "FedCloudSharePermissions",
"data": {"type$": "OBSERVED_CLOUD_SHARE_ACTIVITY",
"id": "4bc378e6-bfbd-40f0-9572-6ed605ea9f6c",
"sources": ["GoogleDrive"],
"exposureTypes": ["PublicLinkShare"],
"firstActivityAt": "2020-05-22T09:40:00.0000000Z",
"lastActivityAt": "2020-05-22T09:45:00.0000000Z",
"fileCount": 1,
"totalFileSize": 6025,
"fileCategories": [{"type$": "OBSERVED_FILE_CATEGORY", "category": "Document", "fileCount": 1, "totalFileSize": 6025, "isSignificant": false}],
"files": [{"type$": "OBSERVED_FILE", "eventId": "1hHdK6Qe6hez4vNCtS-UimDf-sbaFd-D7_3_baac33d0-a1d3-4e0a-9957-25632819eda7", "name": "1590140395_Longfellow_Cloud_Arch_Redesign.drawio", "category": "Document", "size": 6025}],
"outsideTrustedDomainsEmailsCount": 0, "outsideTrustedDomainsTotalDomainCount": 0, "outsideTrustedDomainsTotalDomainCountTruncated": false}}]}
CEF Mapping

The following tables map the file event data from the Code42 CLI to common event format (CEF).

Attribute mapping

The table below maps JSON fields, CEF fields, and Forensic Search fields to one another.

JSON field CEF field Forensic Search field
actor suser Actor
cloudDriveId aid n/a
createTimestamp fileCreateTime File Created Date
deviceUid deviceExternalId n/a
deviceUserName suser Username (Code42)
domainName dvchost Fully Qualified Domain Name
eventId externalID n/a
eventTimestamp end Date Observed
exposure reason Exposure Type
fileCategory fileType File Category
fileName fname Filename
filePath filePath File Path
fileSize fsize File Size
insertionTimestamp rt n/a
md5Checksum fileHash MD5 Hash
modifyTimesamp fileModificationTime File Modified Date
osHostName shost Hostname
processName sproc Executable Name (Browser or Other App)
processOwner spriv Process User (Browser or Other App)
publiclpAddress src IP Address (public)
removableMediaBusType cs1, Code42AEDRemovableMediaBusType Device Bus Type (Removable Media)
removableMediaCapacity cn1, Code42AEDRemovableMediaCapacity Device Capacity (Removable Media)
removableMediaName cs3, Code42AEDRemovableMediaName Device Media Name (Removable Media)
removableMediaSerialNumber cs4 Device Serial Number (Removable Media)
removableMediaVendor cs2, Code42AEDRemovableMediaVendor Device Vendor (Removable Media)
sharedWith duser Shared With
syncDestination destinationServiceName Sync Destination (Cloud)
url filePath URL
userUid suid n/a
windowTitle requestClientApplication Tab/Window Title
tabUrl request Tab URL
emailSender suser Sender
emailRecipients duser Recipients
Event mapping

See the table below to map file events to CEF signature IDs.

Exfiltration event CEF field
CREATED C42200
MODIFIED C42201
DELETED C42202
READ_BY_APP C42203
EMAILED C42204

Manage Detection List Users

Use the departing-employee commands to add employees to or remove employees from the Departing Employees list. Use the high-risk-employee commands to add employees to or remove employees from the High Risk list, or update risk tags for those users.

To see a list of all the users currently in your organization, you can export a list from the Users action menu.

Get CSV template

To add multiple users to the Departing Employees list:

  1. Generate a CSV template. Below is an example command for generating a template to use to add employees to the Departing Employees list. Once generated, the CSV file is saved to your current working directory.
code42 departing-employee bulk generate-template add
  1. Use the CSV template to enter the employees’ information. Only the Code42 username is required. If added, the departure date must be in yyyy-MM-dd format. Note: you are only able to add departure dates during the add operation. If you don’t include --departure-date, you can only add one later by removing and then re-adding the employee.
  2. Save the CSV file.
Add users to the Departing Employees list

Once you have entered the employees’ information in the CSV file, use the bulk add command with the CSV file path to add multiple users at once. For example:

code42 departing-employee bulk add /Users/astrid.ludwig/add_departing_employee.csv
Remove users

You can remove one or more users from the High Risk Employees list. Use code42 departing-employee remove to remove a single user.

To remove multiple users at once:

  1. Create a CSV file with one username per line.
  2. Save the file to your current working directory.
  3. Use the bulk remove command. For example:
code42 high-risk-employee bulk remove /Users/matt.allen/remove_high_risk_employee.csv

Learn more about the Departing Employee and High Risk Employee commands.

Commands

profile

Manage Code42 connection settings.

profile [OPTIONS] COMMAND [ARGS]...
create

Create profile settings. The first profile created will be the default.

profile create [OPTIONS]

Options

-n, --name <name>

Required The name of the Code42 CLI profile to use when executing this command.

-s, --server <server>

Required The URL you use to sign into Code42.

-u, --username <username>

Required The username of the Code42 API user.

--password <password>

The password for the Code42 API user. If this option is omitted, interactive prompts will be used to obtain the password.

--disable-ssl-errors

For development purposes, do not validate the SSL certificates of Code42 servers. This is not recommended, except for specific scenarios like testing.

delete

Deletes a profile and its stored password (if any).

profile delete [OPTIONS] PROFILE_NAME

Options

-y, --assume-yes

Assume “yes” as the answer to all prompts and run non-interactively.

Arguments

PROFILE_NAME

Required argument

delete-all

Deletes all profiles and saved passwords (if any).

profile delete-all [OPTIONS]

Options

-y, --assume-yes

Assume “yes” as the answer to all prompts and run non-interactively.

list

Show all existing stored profiles.

profile list [OPTIONS]
reset-pw
Change the stored password for a profile. Only affects what’s stored in the local profile,
does not make any changes to the Code42 user account.
profile reset-pw [OPTIONS] [PROFILE_NAME]

Arguments

PROFILE_NAME

Optional argument

show

Print the details of a profile.

profile show [OPTIONS] [PROFILE_NAME]

Arguments

PROFILE_NAME

Optional argument

update

Update an existing profile.

profile update [OPTIONS]

Options

-n, --name <name>

The name of the Code42 CLI profile to use when executing this command.

-s, --server <server>

The URL you use to sign into Code42.

-u, --username <username>

The username of the Code42 API user.

--password <password>

The password for the Code42 API user. If this option is omitted, interactive prompts will be used to obtain the password.

--disable-ssl-errors

For development purposes, do not validate the SSL certificates of Code42 servers. This is not recommended, except for specific scenarios like testing.

use

Set a profile as the default.

profile use [OPTIONS] [PROFILE_NAME]

Arguments

PROFILE_NAME

Optional argument

security-data

Get and send file event data.

security-data [OPTIONS] COMMAND [ARGS]...
clear-checkpoint

Remove the saved file event checkpoint from –use-checkpoint/-c mode.

security-data clear-checkpoint [OPTIONS] CHECKPOINT_NAME

Options

-d, --debug

Turn on debug logging.

--profile <profile>

The name of the Code42 CLI profile to use when executing this command.

Arguments

CHECKPOINT_NAME

Required argument

send-to

Send events to the given server address.

HOSTNAME format: address:port where port is optional and defaults to 514.

security-data send-to [OPTIONS] HOSTNAME

Options

Get events from a saved search filter with the given ID.

--include-non-exposure

Get all events including non-exposure events.

--tab-url <tab_url>

Limits events to be exposure events with one of the specified destination tab URLs.

--process-owner <process_owner>

Limits exposure events by process owner, as reported by the device’s operating system. Applies only to Printed and Browser or app read events.

--file-category <file_category>

Limits events to file events where the file can be classified by one of these categories.

Options:AUDIO|DOCUMENT|EXECUTABLE|IMAGE|PDF|PRESENTATION|SCRIPT|SOURCE_CODE|SPREADSHEET|VIDEO|VIRTUAL_DISK_IMAGE|ARCHIVE
--file-path <file_path>

Limits events to file events where the file is located at one of these paths. Applies to endpoint file events only.

--file-name <file_name>

Limits events to file events where the file has one of these names.

--source <source>

Limits events to only those from one of these sources. For example, Gmail, Box, or Endpoint.

--sha256 <sha256>

Limits events to file events where the file has one of these SHA256 hashes.

--md5 <md5>

Limits events to file events where the file has one of these MD5 hashes.

--actor <actor>

Limits events to only those enacted by the cloud service user of the person who caused the event.

--c42-username <c42_username>

Limits events to endpoint events for these Code42 users.

-t, --type <type>

Limits events to those with given exposure types.

Options:ApplicationRead|CloudStorage|IsPublic|OutsideTrustedDomains|RemovableMedia|SharedToDomain|SharedViaLink
-b, --begin <begin>

The beginning of the date range in which to look for file events. Accepts a date/time in yyyy-MM-dd (UTC) or yyyy-MM-dd HH:MM:SS (UTC+24-hr time) format where the ‘time’ portion of the string can be partial (e.g. ‘2020-01-01 12’ or ‘2020-01-01 01:15’) or a ‘short time’ value representing days (30d), hours (24h) or minutes (15m) from the current time.

-e, --end <end>

The end of the date range in which to look for file events, argument format options are the same as –begin.

--advanced-query <QUERY_JSON>

A raw JSON file events query. Useful for when the provided query parameters do not satisfy your requirements. Argument can be passed as a string, read from stdin by passing ‘-‘, or from a filename if prefixed with ‘@’, e.g. ‘–advanced-query @query.json’. WARNING: Using advanced queries is incompatible with other query-building arguments.

-c, --use-checkpoint <use_checkpoint>

Only get file events that were not previously retrieved.

--or-query

Combine query filter options with ‘OR’ logic instead of the default ‘AND’.

-d, --debug

Turn on debug logging.

--profile <profile>

The name of the Code42 CLI profile to use when executing this command.

--ignore-cert-validation

Set to skip CA certificate validation. Incompatible with the ‘certs’ option.

--certs <certs>

A CA certificates-chain file for the TLS protocol.

-p, --protocol <protocol>

Protocol used to send logs to server. Use TLS for additional security. Defaults to UDP.

Options:TCP|UDP|TLS-TCP
--include-all

Display simple properties of the primary level of the nested response.

-f, --format <format>

The output format of the result. Defaults to RAW-JSON format.

Options:CEF|JSON|RAW-JSON

Arguments

HOSTNAME

Required argument

audit-logs

Get and send audit log event data.

audit-logs [OPTIONS] COMMAND [ARGS]...
clear-checkpoint

Remove the saved audit log checkpoint from –use-checkpoint/-c mode.

audit-logs clear-checkpoint [OPTIONS] CHECKPOINT_NAME

Options

-d, --debug

Turn on debug logging.

--profile <profile>

The name of the Code42 CLI profile to use when executing this command.

Arguments

CHECKPOINT_NAME

Required argument

send-to

Send audit log events to the given server address in JSON format.

HOSTNAME format: address:port where port is optional and defaults to 514.

audit-logs send-to [OPTIONS] HOSTNAME

Options

-b, --begin <begin>

The beginning of the date range in which to look for audit-logs. Accepts a date/time in yyyy-MM-dd (UTC) or yyyy-MM-dd HH:MM:SS (UTC+24-hr time) format where the ‘time’ portion of the string can be partial (e.g. ‘2020-01-01 12’ or ‘2020-01-01 01:15’) or a ‘short time’ value representing days (30d), hours (24h) or minutes (15m) from the current time.

-e, --end <end>

The end of the date range in which to look for audit-logs, argument format options are the same as –begin.

--affected-username <affected_username>

Filter results by affected usernames.

--affected-user-id <affected_user_id>

Filter results by affected user IDs.

--actor-ip <actor_ip>

Filter results by user IP addresses.

--actor-user-id <actor_user_id>

Filter results by actor user IDs.

--actor-username <actor_username>

Filter results by actor usernames.

--event-type <event_type>

Filter results by event types (e.g. search_issued, user_registered, user_deactivated).

-c, --use-checkpoint <use_checkpoint>

Only get audit-logs that were not previously retrieved.

--ignore-cert-validation

Set to skip CA certificate validation. Incompatible with the ‘certs’ option.

--certs <certs>

A CA certificates-chain file for the TLS protocol.

-p, --protocol <protocol>

Protocol used to send logs to server. Use TLS for additional security. Defaults to UDP.

Options:TCP|UDP|TLS-TCP
-d, --debug

Turn on debug logging.

--profile <profile>

The name of the Code42 CLI profile to use when executing this command.

Arguments

HOSTNAME

Required argument

alerts

Get and send alert data.

alerts [OPTIONS] COMMAND [ARGS]...
clear-checkpoint

Remove the saved alert checkpoint from –use-checkpoint/-c mode.

alerts clear-checkpoint [OPTIONS] CHECKPOINT_NAME

Options

-d, --debug

Turn on debug logging.

--profile <profile>

The name of the Code42 CLI profile to use when executing this command.

Arguments

CHECKPOINT_NAME

Required argument

send-to

Send alerts to the given server address.

HOSTNAME format: address:port where port is optional and defaults to 514.

alerts send-to [OPTIONS] HOSTNAME

Options

--state <state>

Filter alerts by status. Defaults to returning all statuses.

Options:RESOLVED|IN_PROGRESS|OPEN|PENDING
--severity <severity>

Filter alerts by severity. Defaults to returning all severities.

Options:HIGH|LOW|MEDIUM
--description <description>

Filter alerts by description. Does fuzzy search by default.

--exclude-rule-type <exclude_rule_type>

Filter alerts by excluding the given rule type(s).

--rule-type <rule_type>

Filter alerts by including the given rule type(s).

Options:FedCloudSharePermissions|FedEndpointExfiltration|FedFileTypeMismatch
--exclude-rule-id <exclude_rule_id>

Filter alerts by excluding the given rule id(s).

--rule-id <rule_id>

Filter alerts by including the given rule id(s).

--exclude-rule-name <exclude_rule_name>

Filter alerts by excluding the given rule name(s).

--rule-name <rule_name>

Filter alerts by including the given rule name(s).

--exclude-actor-contains <exclude_actor_contains>

Filter alerts by excluding actor(s) whose cloud alias contains the given string.

--exclude-actor <exclude_actor>

Filter alerts by excluding the given actor(s) who triggered the alert. Arguments must match actor’s cloud alias exactly.

--actor-contains <actor_contains>

Filter alerts by including actor(s) whose cloud alias contains the given string.

--actor <actor>

Filter alerts by including the given actor(s) who triggered the alert. Arguments must match the actor’s cloud alias exactly.

-b, --begin <begin>

The beginning of the date range in which to look for alerts. Accepts a date/time in yyyy-MM-dd (UTC) or yyyy-MM-dd HH:MM:SS (UTC+24-hr time) format where the ‘time’ portion of the string can be partial (e.g. ‘2020-01-01 12’ or ‘2020-01-01 01:15’) or a ‘short time’ value representing days (30d), hours (24h) or minutes (15m) from the current time.

-e, --end <end>

The end of the date range in which to look for alerts, argument format options are the same as –begin.

--advanced-query <QUERY_JSON>

A raw JSON alerts query. Useful for when the provided query parameters do not satisfy your requirements. Argument can be passed as a string, read from stdin by passing ‘-‘, or from a filename if prefixed with ‘@’, e.g. ‘–advanced-query @query.json’. WARNING: Using advanced queries is incompatible with other query-building arguments.

-c, --use-checkpoint <use_checkpoint>

Only get alerts that were not previously retrieved.

--or-query
-d, --debug

Turn on debug logging.

--profile <profile>

The name of the Code42 CLI profile to use when executing this command.

--ignore-cert-validation

Set to skip CA certificate validation. Incompatible with the ‘certs’ option.

--certs <certs>

A CA certificates-chain file for the TLS protocol.

-p, --protocol <protocol>

Protocol used to send logs to server. Use TLS for additional security. Defaults to UDP.

Options:TCP|UDP|TLS-TCP
--include-all

Display simple properties of the primary level of the nested response.

-f, --format <format>

The output format of the result. Defaults to json format.

Options:JSON|RAW-JSON

Arguments

HOSTNAME

Required argument

alert-rules

Manage users associated with alert rules.

alert-rules [OPTIONS] COMMAND [ARGS]...
add-user

Add a user to an alert rule.

alert-rules add-user [OPTIONS]

Options

--rule-id <rule_id>

Required Identification number of the alert rule.

-u, --username <username>

Required The username of the user to add to the alert rule.

-d, --debug

Turn on debug logging.

--profile <profile>

The name of the Code42 CLI profile to use when executing this command.

bulk

Tools for executing bulk alert rule actions.

alert-rules bulk [OPTIONS] COMMAND [ARGS]...
add

Bulk add users to alert rules from a CSV file. CSV file format: rule_id,username

alert-rules bulk add [OPTIONS] CSV_FILE

Options

-d, --debug

Turn on debug logging.

--profile <profile>

The name of the Code42 CLI profile to use when executing this command.

Arguments

CSV_FILE

Required argument

generate-template

Generate the CSV template needed for bulk adding/removing users.

alert-rules bulk generate-template [OPTIONS] [add|remove]

Options

-p, --path <path>

Write template file to specific file path/name.

Arguments

CMD

Required argument

remove

Bulk remove users from alert rules using a CSV file. CSV file format: rule_id,username

alert-rules bulk remove [OPTIONS] CSV_FILE

Options

-d, --debug

Turn on debug logging.

--profile <profile>

The name of the Code42 CLI profile to use when executing this command.

Arguments

CSV_FILE

Required argument

list

Fetch existing alert rules.

alert-rules list [OPTIONS]

Options

-f, --format <format>

The output format of the result. Defaults to table format.

Options:TABLE|CSV|JSON|RAW-JSON
-d, --debug

Turn on debug logging.

--profile <profile>

The name of the Code42 CLI profile to use when executing this command.

remove-user

Remove a user from an alert rule.

alert-rules remove-user [OPTIONS]

Options

--rule-id <rule_id>

Required Identification number of the alert rule.

-u, --username <username>

Required The username of the user to remove from the alert rule.

-d, --debug

Turn on debug logging.

--profile <profile>

The name of the Code42 CLI profile to use when executing this command.

show

Print out detailed alert rule criteria.

alert-rules show [OPTIONS] RULE_ID

Options

-d, --debug

Turn on debug logging.

--profile <profile>

The name of the Code42 CLI profile to use when executing this command.

Arguments

RULE_ID

Required argument

departing-employee

Add and remove employees from the Departing Employees detection list.

departing-employee [OPTIONS] COMMAND [ARGS]...
add

Add a user to the Departing Employees detection list.

departing-employee add [OPTIONS] USERNAME

Options

--departure-date <departure_date>

The date the employee is departing. Format: yyyy-MM-dd.

--cloud-alias <cloud_alias>

If the employee has an email alias other than their Code42 username that they use for cloud services such as Google Drive, OneDrive, or Box, add and monitor the alias. WARNING: Adding a cloud alias will override any existing cloud alias for this user.

--notes <notes>

Optional notes about the employee.

-d, --debug

Turn on debug logging.

--profile <profile>

The name of the Code42 CLI profile to use when executing this command.

Arguments

USERNAME

Required argument

bulk

Tools for executing bulk departing employee actions.

departing-employee bulk [OPTIONS] COMMAND [ARGS]...
add

Bulk add users to the Departing Employees detection list using a CSV file with format: username,cloud_alias,departure_date,notes.

departing-employee bulk add [OPTIONS] CSV_FILE

Options

-d, --debug

Turn on debug logging.

--profile <profile>

The name of the Code42 CLI profile to use when executing this command.

Arguments

CSV_FILE

Required argument

generate-template

Generate the CSV template needed for bulk adding/removing users.

departing-employee bulk generate-template [OPTIONS] [add|remove]

Options

-p, --path <path>

Write template file to specific file path/name.

Arguments

CMD

Required argument

remove

Bulk remove users from the Departing Employees detection list using a line-separated file of usernames.

departing-employee bulk remove [OPTIONS] FILE

Options

-d, --debug

Turn on debug logging.

--profile <profile>

The name of the Code42 CLI profile to use when executing this command.

Arguments

FILE

Required argument

list

Lists the users on the Departing Employees list.

departing-employee list [OPTIONS]

Options

-d, --debug

Turn on debug logging.

--profile <profile>

The name of the Code42 CLI profile to use when executing this command.

-f, --format <format>

The output format of the result. Defaults to table format.

Options:TABLE|CSV|JSON|RAW-JSON
--filter <filter>

Departing employee filter options. Defaults to ALL.

Options:EXFILTRATION_24_HOURS|EXFILTRATION_30_DAYS|LEAVING_TODAY|ALL
remove

Remove a user from the Departing Employees detection list.

departing-employee remove [OPTIONS] USERNAME

Options

-d, --debug

Turn on debug logging.

--profile <profile>

The name of the Code42 CLI profile to use when executing this command.

Arguments

USERNAME

Required argument

devices

Manage devices within your Code42 environment.

devices [OPTIONS] COMMAND [ARGS]...
bulk

Tools for managing devices in bulk.

devices bulk [OPTIONS] COMMAND [ARGS]...
deactivate

Deactivate all devices from the provided CSV containing a ‘guid’ column.

devices bulk deactivate [OPTIONS] CSV_FILE

Options

--change-device-name

Prepend ‘deactivated_<current_date>’ to the name of any successfully deactivated devices.

--purge-date <purge_date>

The date on which the archive should be purged from cold storage in yyyy-MM-dd format. If not provided, the date will be set according to the appropriate organization settings.

-f, --format <format>

The output format of the result. Defaults to table format.

Options:TABLE|CSV|JSON|RAW-JSON
-d, --debug

Turn on debug logging.

--profile <profile>

The name of the Code42 CLI profile to use when executing this command.

Arguments

CSV_FILE

Required argument

generate-template

Generate the CSV template needed for bulk device commands.

devices bulk generate-template [OPTIONS] [reactivate|deactivate]

Options

-p, --path <path>

Write template file to specific file path/name.

Arguments

CMD

Required argument

reactivate

Reactivate all devices from the provided CSV containing a ‘guid’ column.

devices bulk reactivate [OPTIONS] CSV_FILE

Options

-f, --format <format>

The output format of the result. Defaults to table format.

Options:TABLE|CSV|JSON|RAW-JSON
-d, --debug

Turn on debug logging.

--profile <profile>

The name of the Code42 CLI profile to use when executing this command.

Arguments

CSV_FILE

Required argument

deactivate

Deactivate a device within Code42. Requires the device GUID to deactivate.

devices deactivate [OPTIONS] DEVICE_GUID

Options

--change-device-name

Prepend ‘deactivated_<current_date>’ to the name of the device if deactivation is successful.

--purge-date <purge_date>

The date on which the archive should be purged from cold storage in yyyy-MM-dd format. If not provided, the date will be set according to the appropriate organization settings.

-d, --debug

Turn on debug logging.

--profile <profile>

The name of the Code42 CLI profile to use when executing this command.

Arguments

DEVICE_GUID

Required argument

list

Get information about many devices.

devices list [OPTIONS]

Options

--active

Limits results to only active devices.

--inactive

Limits results to only deactivated devices.

--org-uid <org_uid>

Limit devices to only those in the organization you specify. Note that child organizations will be included.

--include-backup-usage

Return backup usage information for each device (may significantly lengthen the size of the return).

--include-usernames

Add the username associated with a device to the output.

--include-settings

Include device settings in output.

--exclude-most-recently-connected <exclude_most_recently_connected>

Filter out the N most recently connected devices per user. Useful for identifying duplicate and/or replaced devices that are no longer needed across an environment. If a user has 2 devices and N=1, the one device with the most recent ‘lastConnected’ date will not show up in the result list.

--last-connected-before <last_connected_before>

Include devices only when the ‘lastConnected’ field is after the provided value. Accepts a date/time in yyyy-MM-dd (UTC) or yyyy-MM-dd HH:MM:SS (UTC+24-hr time) format where the ‘time’ portion of the string can be partial (e.g. ‘2020-01-01 12’ or ‘2020-01-01 01:15’) or a ‘short time’ value representing days (30d), hours (24h) or minutes (15m) from the current time.

--last-connected-after <last_connected_after>

Include devices only when ‘lastConnected’ field is after the provided value. Argument format options are the same as –last-connected-before.

--created-before <created_before>

Include devices only when ‘creationDate’ field is less than the provided value. Argument format options are the same as –last-connected-before.

--created-after <created_after>

Include devices only when ‘creationDate’ field is greater than the provided value. Argument format options are the same as –last-connected-before.

-f, --format <format>

The output format of the result. Defaults to table format.

Options:TABLE|CSV|JSON|RAW-JSON
-d, --debug

Turn on debug logging.

--profile <profile>

The name of the Code42 CLI profile to use when executing this command.

list-backup-sets

Get information about many devices and their backup sets.

devices list-backup-sets [OPTIONS]

Options

--active

Limits results to only active devices.

--inactive

Limits results to only deactivated devices.

--org-uid <org_uid>

Limit devices to only those in the organization you specify. Note that child organizations will be included.

--include-usernames

Add the username associated with a device to the output.

-f, --format <format>

The output format of the result. Defaults to table format.

Options:TABLE|CSV|JSON|RAW-JSON
-d, --debug

Turn on debug logging.

--profile <profile>

The name of the Code42 CLI profile to use when executing this command.

reactivate

Reactivate a device within Code42. Requires the device GUID to reactivate.

devices reactivate [OPTIONS] DEVICE_GUID

Options

-d, --debug

Turn on debug logging.

--profile <profile>

The name of the Code42 CLI profile to use when executing this command.

Arguments

DEVICE_GUID

Required argument

show

Print individual device details. Requires device GUID.

devices show [OPTIONS] DEVICE_GUID

Options

-d, --debug

Turn on debug logging.

--profile <profile>

The name of the Code42 CLI profile to use when executing this command.

Arguments

DEVICE_GUID

Required argument

high-risk-employee

Add and remove employees from the High Risk Employees detection list.

high-risk-employee [OPTIONS] COMMAND [ARGS]...
add

Add a user to the high risk employees detection list.

high-risk-employee add [OPTIONS] USERNAME

Options

--cloud-alias <cloud_alias>

If the employee has an email alias other than their Code42 username that they use for cloud services such as Google Drive, OneDrive, or Box, add and monitor the alias. WARNING: Adding a cloud alias will override any existing cloud alias for this user.

--notes <notes>

Optional notes about the employee.

-t, --risk-tag <risk_tag>

Risk tags associated with the employee.

Options:CONTRACT_EMPLOYEE|ELEVATED_ACCESS_PRIVILEGES|FLIGHT_RISK|HIGH_IMPACT_EMPLOYEE|PERFORMANCE_CONCERNS|POOR_SECURITY_PRACTICES|SUSPICIOUS_SYSTEM_ACTIVITY
-d, --debug

Turn on debug logging.

--profile <profile>

The name of the Code42 CLI profile to use when executing this command.

Arguments

USERNAME

Required argument

add-risk-tags

Associates risk tags with a user.

high-risk-employee add-risk-tags [OPTIONS] USERNAME

Options

-t, --risk-tag <risk_tag>

Risk tags associated with the employee.

Options:CONTRACT_EMPLOYEE|ELEVATED_ACCESS_PRIVILEGES|FLIGHT_RISK|HIGH_IMPACT_EMPLOYEE|PERFORMANCE_CONCERNS|POOR_SECURITY_PRACTICES|SUSPICIOUS_SYSTEM_ACTIVITY
-d, --debug

Turn on debug logging.

--profile <profile>

The name of the Code42 CLI profile to use when executing this command.

Arguments

USERNAME

Required argument

bulk

Tools for executing high risk employee actions in bulk.

high-risk-employee bulk [OPTIONS] COMMAND [ARGS]...
add

Bulk add users to the high risk employees detection list using a CSV file with format: username,cloud_alias,risk_tag,notes.

high-risk-employee bulk add [OPTIONS] CSV_FILE

Options

-d, --debug

Turn on debug logging.

--profile <profile>

The name of the Code42 CLI profile to use when executing this command.

Arguments

CSV_FILE

Required argument

add-risk-tags

Adds risk tags to users in bulk using a CSV file with format: username,tag.

high-risk-employee bulk add-risk-tags [OPTIONS] CSV_FILE

Options

-d, --debug

Turn on debug logging.

--profile <profile>

The name of the Code42 CLI profile to use when executing this command.

Arguments

CSV_FILE

Required argument

generate-template

Generate the CSV template needed for bulk adding/removing users.

high-risk-employee bulk generate-template [OPTIONS] [add|remove|add-risk-
                                          tags|remove-risk-tags]

Options

-p, --path <path>

Write template file to specific file path/name.

Arguments

CMD

Required argument

remove

Bulk remove users from the high risk employees detection list using a line-separated file of usernames.

high-risk-employee bulk remove [OPTIONS] FILE

Options

-d, --debug

Turn on debug logging.

--profile <profile>

The name of the Code42 CLI profile to use when executing this command.

Arguments

FILE

Required argument

remove-risk-tags

Removes risk tags from users in bulk using a CSV file with format: username,tag.

high-risk-employee bulk remove-risk-tags [OPTIONS] CSV_FILE

Options

-d, --debug

Turn on debug logging.

--profile <profile>

The name of the Code42 CLI profile to use when executing this command.

Arguments

CSV_FILE

Required argument

list

Lists the employees on the High Risk Employee list.

high-risk-employee list [OPTIONS]

Options

-d, --debug

Turn on debug logging.

--profile <profile>

The name of the Code42 CLI profile to use when executing this command.

-f, --format <format>

The output format of the result. Defaults to table format.

Options:TABLE|CSV|JSON|RAW-JSON
--filter <filter>

High risk employee filter options. Defaults to ALL.

Options:EXFILTRATION_24_HOURS|EXFILTRATION_30_DAYS|ALL
remove

Remove a user from the high risk employees detection list.

high-risk-employee remove [OPTIONS] USERNAME

Options

-d, --debug

Turn on debug logging.

--profile <profile>

The name of the Code42 CLI profile to use when executing this command.

Arguments

USERNAME

Required argument

remove-risk-tags

Disassociates risk tags from a user.

high-risk-employee remove-risk-tags [OPTIONS] USERNAME

Options

-t, --risk-tag <risk_tag>

Risk tags associated with the employee.

Options:CONTRACT_EMPLOYEE|ELEVATED_ACCESS_PRIVILEGES|FLIGHT_RISK|HIGH_IMPACT_EMPLOYEE|PERFORMANCE_CONCERNS|POOR_SECURITY_PRACTICES|SUSPICIOUS_SYSTEM_ACTIVITY
-d, --debug

Turn on debug logging.

--profile <profile>

The name of the Code42 CLI profile to use when executing this command.

Arguments

USERNAME

Required argument

cases

Manage cases and events associated with cases.

cases [OPTIONS] COMMAND [ARGS]...
create

Create a new case.

cases create [OPTIONS] NAME

Options

--assignee <assignee>

The UID of the user to assign to the case.

--description <description>

The description of the case.

--findings <findings>

Any findings for the case.

--subject <subject>

The user UID of the subject of the case.

-d, --debug

Turn on debug logging.

--profile <profile>

The name of the Code42 CLI profile to use when executing this command.

Arguments

NAME

Required argument

export

Download a case detail summary as a PDF file at the given path with name <case_number>_case_summary.pdf.

cases export [OPTIONS] CASE_NUMBER

Options

--path <path>

The file path where to save the PDF. Defaults to the current directory.

-d, --debug

Turn on debug logging.

--profile <profile>

The name of the Code42 CLI profile to use when executing this command.

Arguments

CASE_NUMBER

Required argument

file-events

Fetch file events associated with the case.

cases file-events [OPTIONS] COMMAND [ARGS]...

Options

-d, --debug

Turn on debug logging.

--profile <profile>

The name of the Code42 CLI profile to use when executing this command.

add

Associate a file event to a case, by event ID.

cases file-events add [OPTIONS]

Options

--case-number <case_number>

Required The number assigned to the case.

--event-id <event_id>

Required The file event ID associated with the case.

-d, --debug

Turn on debug logging.

--profile <profile>

The name of the Code42 CLI profile to use when executing this command.

list

List all the file events associated with the case.

cases file-events list [OPTIONS] CASE_NUMBER

Options

-d, --debug

Turn on debug logging.

--profile <profile>

The name of the Code42 CLI profile to use when executing this command.

-f, --format <format>

The output format of the result. Defaults to table format.

Options:TABLE|CSV|JSON|RAW-JSON

Arguments

CASE_NUMBER

Required argument

remove

Remove the associated file event from the case, by event ID.

cases file-events remove [OPTIONS]

Options

--case-number <case_number>

Required The number assigned to the case.

--event-id <event_id>

Required The file event ID associated with the case.

-d, --debug

Turn on debug logging.

--profile <profile>

The name of the Code42 CLI profile to use when executing this command.

list

List all the cases.

cases list [OPTIONS]

Options

--name <name>

Filter by name of a case. Supports partial name matches.

--subject <subject>

Filter by the user UID of the subject of a case.

--assignee <assignee>

Filter by the user UID of an assignee.

--begin-create-time <begin_create_time>

The beginning of the date range in which to look for cases. Accepts a date/time in yyyy-MM-dd (UTC) or yyyy-MM-dd HH:MM:SS (UTC+24-hr time) format where the ‘time’ portion of the string can be partial (e.g. ‘2020-01-01 12’ or ‘2020-01-01 01:15’) or a ‘short time’ value representing days (30d), hours (24h) or minutes (15m) from the current time.

--end-create-time <end_create_time>

The end of the date range in which to look for cases, argument format options are the same as –begin.

--begin-update-time <begin_update_time>

The beginning of the date range in which to look for cases. Accepts a date/time in yyyy-MM-dd (UTC) or yyyy-MM-dd HH:MM:SS (UTC+24-hr time) format where the ‘time’ portion of the string can be partial (e.g. ‘2020-01-01 12’ or ‘2020-01-01 01:15’) or a ‘short time’ value representing days (30d), hours (24h) or minutes (15m) from the current time.

--end-update-time <end_update_time>

The end of the date range in which to look for cases, argument format options are the same as –begin.

--status <status>

Filter cases by case status.

-f, --format <format>

The output format of the result. Defaults to table format.

Options:TABLE|CSV|JSON|RAW-JSON
-d, --debug

Turn on debug logging.

--profile <profile>

The name of the Code42 CLI profile to use when executing this command.

show

Show case details.

cases show [OPTIONS] CASE_NUMBER

Options

--include-file-events

View file events associated to the case.

-d, --debug

Turn on debug logging.

--profile <profile>

The name of the Code42 CLI profile to use when executing this command.

-f, --format <format>

The output format of the result. Defaults to table format.

Options:TABLE|CSV|JSON|RAW-JSON

Arguments

CASE_NUMBER

Required argument

update

Update case details for the given case.

cases update [OPTIONS] CASE_NUMBER

Options

--name <name>

The name of the case.

--assignee <assignee>

The UID of the user to assign to the case.

--description <description>

The description of the case.

--findings <findings>

Any findings for the case.

--subject <subject>

The user UID of the subject of the case.

--status <status>

Status of the case. OPEN or CLOSED.

Options:CLOSED|OPEN
-d, --debug

Turn on debug logging.

--profile <profile>

The name of the Code42 CLI profile to use when executing this command.

Arguments

CASE_NUMBER

Required argument