ruby --versionin a terminal.
gemin a Terminal. If you got it already, it is recommended to do a quick
gem update --systemto make sure you have the latest and greatest version. In case you don’t have it installed, download it from here and follow the simple installation instructions.
service postgresql startand install a dependency with
apt-get install libpq-devin a terminal. Here’s an excellent guide on how to install PostgreSQL on a Debian based Linux system. If you are setting up Gitrob on a Mac, the easiest way to install PostgreSQL is with Homebrew. Here’s a guide on how to install PostgreSQL with Homebrew.
3.1 PostgreSQL user and database
You need to set up a user and a database in PostgreSQL for Gitrob. Execute the following commands in a terminal:
You now have a new PostgreSQL user with the name
gitrob and with the password you typed into the prompt. You also created a database with the name
gitrob which is owned by the
Gitrob works by querying the GitHub API for interesting information, so you need at least one access token to get up and running. The easiest way is to create a Personal Access Token. Press the
Generate new tokenbutton and give the token a description. If you intend on using Gitrob against organizations you’re not a member of you don’t need to give the token any scopes, as we will only be accessing public data. If you intend to run Gitrob against your own organization, you’ll need to check the
read:orgscope to get full coverage.
If you plan on using Gitrob extensively or against a very large organization, it might be necessary to have multiple access tokens to avoid running into rate limiting. These access tokens will have to be from different user accounts.
With all the previous steps completed, you can now finally install Gitrob itself with the following command in a terminal:
6. Configuring Gitrob
Gitrob needs to know how to talk to the PostgreSQL database as well as what access token to use to access the GitHub API. Gitrob comes with a convenient configuration wizard which can be invoked with the following command in a terminal:
~/.gitrobrcand yes, Gitrob will be looking for this file too, so watch out!
Analyzing organizations and users
Analyzing organizations and users is the main feature of Gitrob. The
analyze command accepts an arbitrary amount of organization and user logins, which will be bundled into an assessment:
When the assessment is finished, the
analyzecommand will automatically start up the web server to present the results. This can be avoided by adding the
--no-serveroption to the command.
gitrob help analyzefor more options.
Running Gitrob against custom GitHub Enterprise installations
Gitrob can analyze organizations and users on custom GitHub Enterprise installations instead of the official GitHub site. The
analyze command takes several options to control this:
gitrob help analyzefor more options.
The Gitrob web server can be started with the
If you want to look for files that are specific to your organisation or projects, it is easy to add custom signatures.
When Gitrob starts it looks for a file at
~/.gitrobsignatureswhich it expects to be a JSON document with signatures that follow the same structure as the main signatures.json file. Here is an example:
otr.private_key. The caption and description are used in the web interface when displaying the findings.
part: Can be one of:
path: The complete file path
filename: Only the filename
extension: Only the file extension
type: Can be one of:
match: Simple match of part and pattern
regex: Regular expression matching of part and pattern
pattern: The value or regular expression to match with
caption: A short description of the finding
description: More detailed description if needed (set to
Have a look at the main signatures.json file for more examples of signatures.