Skip to main content

Deploying the BluBracket Scanner

Maurice Evans 

# macOS/Linux
./bluscanner --scan-path "/PATH/TO/SCAN" --output scanner.log --verbose \ 
--api-key-file "/PATH/TO/API_KEY/apikey.json" --server-url https://server.example.com

# Windows
.\bluscanner.exe --scan-path "C:\PATH\TO\SCAN" --output scanner.log --verbose \
--api-key-file "C:\PATH\TO\API_KEY\apikey.json" --server-url https://server.example.com

The BluBracket Scanner is an executable that can run on Windows, OSX and Linux desktops and servers and allows insights into the Git repositories located on an end user’s machine.


The BluBracket Scanner can be deployed locally to an individual desktop/server where it can be run via the command line or scripts.  It can also be deployed and managed using software management tools such as SCCM, Jamf, Tanium, etc.


This document will go into detail about the following topics:

  • What platforms does the Scanner run on?

  • Where do I get the Scanner?

  • Where do I get an API Key?

  • Running the BluBracket Scanner

  • What is being scanned, scanned for and what is recorded by the BluBracket Scanner?

What platforms does the BluBracket Scanner run on?

The BluBracket Scanner is an executable that can run on Windows, OSX and Linux desktops and servers.  The downloaded .tgz file will contain all three executable file types for Windows, Mac and Linux.

Where do I get the BluBracket Scanner?

The BluBracket Scanner can be downloaded from the BluBracket tenant portal.

Here’s where you can find the software:

  1. Log into your Blubracket tenant and navigate to the Settings tab in the left navigation bar.

  2. Select the Code Scanning tab at the top of the page.

  3. Scroll to the bottom of the page where you will see the “Download Scanner” section.

  4. Click on the “Download” button.

The downloaded .tgz file will contain all three executable file types for Windows, Mac and Linux.

Where do I get an API Key?

In order to securely communicate with the customer’s BluBracket tenant, the scanner must have an API key that allows the scanner to identify itself.  This API key can be obtained by taking the following steps:

  1. Log into your BluBracket tenant and navigate to the Settings tab in the left navigation bar.

  2. Select the API Keys tab at the top of the page and click on the API Keys section below the tab to expand the section.

  3. Enter a name to identify the API key - anything that might help differentiate the key in the future.

  4. Click on the Generate Key button - this will become available once a key name has been entered.

  5. A dialog will appear that allows the copying of the ID and API key as well as the downloading of the JSON and CSV files that contain the ID and API key.  Make sure you either copy the key or download the JSON or CSV file - you will not be able to obtain the API key again after closing the dialog.  

Running the BluBracket Scanner

The BluBracket Scanner can be run as an executable on any of the supported platforms mentioned above.  This can be done manually or with software management tools such as SCCM, Jamf, Tanium, etc. This section will walk through a few key topics with regards to running the executable and explain usage items.

Once the .tgz file has been downloaded and has been expanded, all three executable types should be exposed in their respective folders.  Move the appropriate folder to a desired location and place the corresponding JSON file in the same folder as the executable.

Run the executable with the following parameter usage options (double-clicking the executable is not recommended - please use bash, command line, PowerShell, etc instead):

--help 

Displays usage types

--scan-path arg

Path to scan

--server-url arg

Tenant Server URL

--api-key-file arg

API Key File Name

--output arg 

Output log to a file name

--output-json arg

Output scan to a JSON file name

--verbose

Verbose output

--scan-network-paths

Scan network locations - Default OFF

--scan-docker-images

Scan Docker images - Default OFF

--scan-archives

Scan archives - Default OFF

--scan-sources

Scan sources - Default OFF

--disable-scan-secrets

Disable scan for secrets in code

Sample command line running the OSX executable:  

mauriceevans@Maurices-MBP osx % ./bluscanner --scan-path ~ --server-url https://maurice.blucodon.com --api-key-file NewScannerKey2_apikey.json --verbose --output-json json-output-file-name --output output-file-name

mauriceevans@Maurices-MBP osx % ./bluscanner --scan-path ~ --server-url https://maurice.blucodon.com --api-key-file NewScannerKey2_apikey.json --verbose --output-json json-output-file-name --output output-file-name

What is being scanned, scanned for and what is recorded by the BluBracket Scanner?

What is scanned by the BluBracket Scanner will depend on the configured usage options, but assuming all options are being leveraged the following would be scanned for on the given locations:

  • Git repository names

  • Git repository types

  • Git repository clones

  • Git repository paths

  • Secrets found within the Git repositories

  • Device type being scanned

  • Device IP address

  • User who cloned the Git repository

  • Contributors to the cloned Git repository

Related articles

Comments

0 comments

Please sign in to leave a comment.

Powered by Zendesk