command-line interface overview

Analysts can perform a number of tasks from either the command line of the *nix shell or from the comments field of a container through the PhBot CLI interpreter in .

The command-line interface in supports a number of tasks:

• Run an action
• Run a playbook
• Add a note to a container
• Update or edit a container
• Get datapath information for use with other actions

Each task type has an associated slash command and arguments.

Use the CLI tool in

You can access the command line interface from the Linux shell by running a script with the required command and arguments. You can find the script in <PHANTOM_HOME>/bin/run_slash_command.pyc.

If you choose to use the CLI tool from a Linux shell, you are prompted to authenticate for each command unless the PH_AUTH_TOKEN or PHANTOM_USERNAME and PHANTOM_PASSWORD environment variables are set. Use the username and password for a valid Phantom user, which might be different from the Linux user account. User credentials are not cached.

You can set environment variables for the Linux user account using the setenv command or by editing the user account's profile.

You can also use the PH_AUTH_TOKEN environment variable for a temporary session as shown in the following example:

export PH_AUTH_TOKEN="<token>"

phenv python run_slash_command.pyc --help

If you use sudo to use slash commands and want to use the PH_AUTH_TOKEN environment variable, use the -E argument to preserve the environment variable.

Anatomy of a slash command

A slash command is an instruction that begins with a forward slash ( / ) followed by a predefined command then any required or optional arguments. Each command has a series of arguments needed for the execution of the command. The order of arguments is important.

You can use the --help argument with a slash command to determine which arguments are needed and in what order they need to be listed.

Use the following format for the action slash command:

/action < action_name > < app > < required arguments > < --asset asset_name> < --optional arguments > 

This example shows the slash command /action followed by the action_name, then the required app to run the action, and finally the required arguments.

/action geolocate_ip "MaxMind" 1.1.1.1

Slash command examples with the CLI tool

Run the run_slash_command.pyc script without arguments to get the help output.

Command:

phenv python run_slash_command.pyc

Output:

    run_slash_command.pyc USAGE: <container-id> <slash-command>

    You will be prompted for authentication. You can set the following environment
    variables to avoid this:

    Environment:
      PH_AUTH_TOKEN:    Authenticate using an auth token.
      PHANTOM_USERNAME: Authenticate with user name. Requires PHANTOM_PASSWORD set to avoid prompt.
      PHANTOM_PASSWORD: Authenticate with password.

    Hint: You can get the container ID from the phantom event UI, /mission/<container-id>/

    Examples:
      - phenv run_slash_command.pyc 1 /action geolocate_ip "MaxMind" 1.1.1.1
      - phenv run_slash_command.pyc 1 /playbook 12 all
      - phenv run_slash_command.pyc 1 /set name "My Container Name"
      - phenv run_slash_command.pyc 1 /note "Errant IPs" IPs encountered include 'artifact:*.network.src_ip'
      - phenv run_slash_command.pyc 1 /inspect 'artifact:*'
      - phenv run_slash_command.pyc 1 /inspect '[1, 2, 3, 4, 5]'

Use the CLI tool to add a note to a container.

Command:

phenv python run_slash_command.pyc <container ID> /note "Errant IPs" IPs encountered include 'artifact:*.network.src_ip'

Output:

[2019-12-12 00:02:08] Execution result was:

Command finished successfully!

The web interface has a new note for the container with the title "Errant IPs" and the body:

IPs encountered include 1.1.1.1

Use the CLI in the web interface

Analysts can use the CLI from the comments field on events or cases in Investigation. When using this method to run commands, slash commands run against the current container.

In the web-based interface, slash commands support auto-completion of options and arguments. Results are displayed in the activity sidebar.