vulcan-cli

README

Vulcan CLI

The vulcan-api-cli is the autogenerated CLI for interacting with vulcan-api, but it's hard to deal with teams/assets/groups/recipients overview, creation or modification.

That's the purpose of vulcan-cli, make easy interaction with the API using files.

$ vulcan-cli -h
Rich CLI to interact with vulcan-api

Usage:
  vulcan-cli [command]

Available Commands:
  help        Help about any command
  import      Import assets in Vulcanito format into vulcan-api
  pull        Dowloads all the info of a team(s) into files inside a directory, overwriting the local info
  push        Uploads the info of a team with the one that is defined in files, overwriting the remote info

Flags:
      --dump               Dump HTTP request and response.
      --format string      Format used to create auth header or query from key (default "Bearer %s")
  -h, --help               help for vulcan-cli
  -H, --host string        API hostname (default "localhost:8080")
  -k, --key string         API key used for authentication
  -s, --scheme string      Set the requests scheme (default "http")
  -t, --timeout duration   Set the request timeout (default 20s)

Use "vulcan-cli [command] --help" for more information about a command.

Let's review the available commands.

Import

First we implemented the import command that allows to import in the API teams, assets and recipients defined in the old Vulcanito assets format.

Example of assets format:

$ ls
index.txt  test/

$ ls test/
aws.txt        domains.txt    emails.txt     hostnames.txt  ips.txt        nessus.txt

$ find test/ -type f -print -exec cat '{}' \;
test//aws.txt
12345453453453
test//domains.txt
example.com
test//emails.txt
test@example.com
test//nessus.txt
test.example.com
test//ips.txt
test//hostnames.txt
test.example.com
sensitive.example.com

It's the easiest way to create new teams!

$ vulcan-cli import -h
Import assets in Vulcanito format into vulcan-api

Usage:
  vulcan-cli import <vulcanito_assets_dir> [flags]

Flags:
  -h, --help   help for import

Global Flags:
      --dump               Dump HTTP request and response.
      --format string      Format used to create auth header or query from key (default "Bearer %s")
  -H, --host string        API hostname (default "localhost:8080")
  -k, --key string         API key used for authentication
  -s, --scheme string      Set the requests scheme (default "http")
  -t, --timeout duration   Set the request timeout (default 20s)

Example: vulcan-cli --key $(cat /tmp/temp-token) import /tmp/vulcanito-assets

Pull

Having an overview of what is created in the API is hard, so let's make it easier.

$ vulcan-cli pull -h
Dowloads all the info of a team(s) into files inside a directory, overwriting the local info

Usage:
  vulcan-cli pull <teams_dir> <team_name> [flags]

Flags:
  -f, --force   Force overwrite of local team, otherwise pull is aborted if team exists locally
  -h, --help    help for pull

Global Flags:
      --dump               Dump HTTP request and response.
      --format string      Format used to create auth header or query from key (default "Bearer %s")
  -H, --host string        API hostname (default "localhost:8080")
  -k, --key string         API key used for authentication
  -s, --scheme string      Set the requests scheme (default "http")
  -t, --timeout duration   Set the request timeout (default 20s)

For the specified team (or all if the all keyword is specified as name) the command pulls:

• the recipients
• the full list of assets
• the groups (embedding the assets that pertain to them)
• a list of orphan assets (assets that does not belong to any group)
• a list of assets that are not in the full list of assets but that are associated to a group (this shouldn't happen anymore)

Example: vulcan-cli --key $(cat /tmp/temp-token) pull . 'Test Team'

$ ls
Test Team/

$ ls Test\ Team/
Default;2cbe421a-aec7-4e90-b51b-0f173f52b773*   assets.txt*                                     orphan.txt*
Sensitive;3a13e790-3e19-4f08-9481-7b22e1762f3f* emails.txt*                                     team.txt*

$ find Test\ Team/ -type f -print -exec cat '{}' \;
Test Team//team.txt
Test Team;;4694c8e1-4acb-4143-b7e3-944bf44effdf
Test Team//Default;2cbe421a-aec7-4e90-b51b-0f173f52b773
example.com;DomainName;3b22792f-18e5-4ee6-aa8b-e049c3959829
test.example.com;Hostname;eaae820c-2dbb-4d0d-bb16-24f95c3b475f
12345453453453;AWSAccount;34a58e53-74a8-4b45-94eb-df9b23f9b4c3
Test Team//orphan.txt
Test Team//emails.txt
test@example.com
Test Team//assets.txt
example.com;DomainName;3b22792f-18e5-4ee6-aa8b-e049c3959829
test.example.com;Hostname;eaae820c-2dbb-4d0d-bb16-24f95c3b475f
sensitive.example.com;Hostname;3dc00d82-98ea-4355-a72b-4181d1d2a9fe
12345453453453;AWSAccount;34a58e53-74a8-4b45-94eb-df9b23f9b4c3
Test Team//Sensitive;3a13e790-3e19-4f08-9481-7b22e1762f3f
sensitive.example.com;Hostname;3dc00d82-98ea-4355-a72b-4181d1d2a9fe

Push

And finally, let's modify assets and push changes.

$ vulcan-cli --key $(cat /tmp/temp-token) push -h
Uploads the info of a team with the one that is defined in files, overwriting the remote info

Usage:
  vulcan-cli push <teams_dir> <team_name> [flags]

Flags:
  -f, --force   Push changes to remote, otherwise performs a dry run only
  -h, --help    help for push

Global Flags:
      --dump               Dump HTTP request and response.
      --format string      Format used to create auth header or query from key (default "Bearer %s")
  -H, --host string        API hostname (default "localhost:8080")
  -k, --key string         API key used for authentication
  -s, --scheme string      Set the requests scheme (default "http")
  -t, --timeout duration   Set the request timeout (default 20s)

For modifying the recipients, just update the emails.txt file.

To create a new group just create a new file with the name of the group. Example: echo "" > NewGroup

To create new assets, just edit the file of the group you want to add the asset to, an add the assets without specifying an ID. It can be done in new groups too :)

To associate existing assets just copy the asset line from one group the other (or from the assets.txt or orphans.txt lists).

To deassociate them, just delete the lines from the group files.

When running the push command without the -f flag, it will only show you the changes to make (dry run). When forced, it pushes the info to the API.

That's it. If you want to see a demo just play the asciicast :)

Scan, Review, Send

$ vulcan-cli -H vulcan.example.com -k $(cat ~/.vulcan-api-token-dev) scan /tmp/assets/ "Vulcan Team"
2019/04/09 16:58:25 [INFO] started id=/KBgdVVn POST=https://vulcan.example.com/api/v1/teams/ba2f2a9b-1ea8-4a28-9519-eab4ed290866/scans
2019/04/09 16:58:26 [INFO] completed id=/KBgdVVn status=201 time=958.661143ms
[*] Writing scans to file '/var/folders/j0/59t1xk6116qbgbzy3qz4v4740000gn/T/vulcan-scan-354488336.txt'

$ cat /var/folders/j0/59t1xk6116qbgbzy3qz4v4740000gn/T/vulcan-scan-354488336.txt
periodic-full-scan;CREATED;Vulcan Team;1e6717df-dc40-46ba-8673-8e3a7a738bdd

$ vulcan-cli -H vulcan.example.com -k $(cat ~/.vulcan-api-token-dev) scan refresh /var/folders/j0/59t1xk6116qbgbzy3qz4v4740000gn/T/vulcan-scan-354488336.txt
2019/04/09 16:59:16 [INFO] started id=nPdoRkxl GET=https://vulcan.example.com/api/v1/teams
2019/04/09 16:59:17 [INFO] completed id=nPdoRkxl status=200 time=603.788877ms
2019/04/09 16:59:17 [INFO] started id=QdoTwezh GET=https://vulcan.example.com/api/v1/teams/ba2f2a9b-1ea8-4a28-9519-eab4ed290866/scans/1e6717df-dc40-46ba-8673-8e3a7a738bdd
2019/04/09 16:59:17 [INFO] completed id=QdoTwezh status=200 time=110.124293ms
periodic-full-scan;RUNNING;Vulcan Team;1e6717df-dc40-46ba-8673-8e3a7a738bdd

$ vulcan-cli -H vulcan.example.com -k $(cat ~/.vulcan-api-token-dev) scan refresh /var/folders/j0/59t1xk6116qbgbzy3qz4v4740000gn/T/vulcan-scan-354488336.txt
2019/04/09 17:13:47 [INFO] started id=+rtijCK/ GET=https://vulcan.example.com/api/v1/teams
2019/04/09 17:13:48 [INFO] completed id=+rtijCK/ status=200 time=408.593893ms
2019/04/09 17:13:48 [INFO] started id=Zu6+m+tF GET=https://vulcan.example.com/api/v1/teams/ba2f2a9b-1ea8-4a28-9519-eab4ed290866/scans/1e6717df-dc40-46ba-8673-8e3a7a738bdd
2019/04/09 17:13:48 [INFO] completed id=Zu6+m+tF status=200 time=268.202334ms
periodic-full-scan;FINISHED;Vulcan Team;1e6717df-dc40-46ba-8673-8e3a7a738bdd

$ vulcan-cli -H vulcan.example.com -k $(cat ~/.vulcan-api-token-dev) scan report --scan-file /var/folders/j0/59t1xk6116qbgbzy3qz4v4740000gn/T/vulcan-scan-354488336.txt
2019/04/09 17:14:35 [INFO] started id=W9hq6X1D GET=https://vulcan.example.com/api/v1/teams
2019/04/09 17:14:35 [INFO] completed id=W9hq6X1D status=200 time=326.289085ms
2019/04/09 17:14:35 [INFO] started id=AEPXS1zI GET=https://vulcan.example.com/api/v1/teams/ba2f2a9b-1ea8-4a28-9519-eab4ed290866/scans/1e6717df-dc40-46ba-8673-8e3a7a738bdd/report/email
2019/04/09 17:14:35 [INFO] completed id=AEPXS1zI status=200 time=52.245906ms
[*] Writing report emails to file '/var/folders/j0/59t1xk6116qbgbzy3qz4v4740000gn/T/vulcan-reports-044883121'

$ ll /var/folders/j0/59t1xk6116qbgbzy3qz4v4740000gn/T/vulcan-reports-044883121
total 64
-rw-r--r--  1 julianvilas  staff    29K Apr  9 17:14 Vulcan Team.html

$ head /var/folders/j0/59t1xk6116qbgbzy3qz4v4740000gn/T/vulcan-reports-044883121/Vulcan\ Team.html
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
	<head>
        <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
        <title>Security Overview - Vulcan Team</title>
        <style type="text/css">
			/* /\/\/\/\/\/\/\/\/ CLIENT-SPECIFIC STYLES /\/\/\/\/\/\/\/\/ */
			#outlook a{padding:0;} /* Force Outlook to provide a "view in browser" message */
			.ReadMsgBody{width:100%;} .ExternalClass{width:100%;} /* Force Hotmail to display emails at full width */
			.ExternalClass, .ExternalClass p, .ExternalClass span, .ExternalClass font, .ExternalClass td, .ExternalClass div {line-height: 100%;} /* Force Hotmail to display normal line spacing */

$ vulcan-cli -H vulcan.example.com -k $(cat ~/.vulcan-api-token-dev) scan report send --scan-file /var/folders/j0/59t1xk6116qbgbzy3qz4v4740000gn/T/vulcan-scan-354488336.txt
2019/04/09 17:16:01 [INFO] started id=vddPWSjO GET=https://vulcan.example.com/api/v1/teams
2019/04/09 17:16:01 [INFO] completed id=vddPWSjO status=200 time=407.480497ms
2019/04/09 17:16:01 [INFO] started id=/XIODrpx POST=https://vulcan.example.com/api/v1/teams/ba2f2a9b-1ea8-4a28-9519-eab4ed290866/scans/1e6717df-dc40-46ba-8673-8e3a7a738bdd/report/send
2019/04/09 17:16:01 [INFO] completed id=/XIODrpx status=200 time=270.11222ms