Semmle 1.21
Skip to end of metadata
Go to start of metadata

This topic describes how to manually create a credentials store to securely manage the credentials required by Semmle tools—for example, to hold the account details required to access source code repositories.

Overview

Semmle Core needs access to source code repositories, servers and systems that are protected by authentication processes. You can enable access, while maintaining security, by using the credentials tool to store authentication details in a credentials store file. The credentials stored in this file can be accessed by tools that need to authenticate with source code repositories, or with other secure systems.

Creating a credentials store

You can create a credentials store using the credentials tool and specifying the --create behavior flag.

To create a new credentials store
  1. Set up your Semmle environment (see Setting up the environment for details).
  2. Run the credentials tool, defining the name and location of the credentials file to create, for example:
    odasa credentials --create --credentials /<path>/credentials-store.xml
  3. You are prompted to choose a password for the store. Alternatively, you can leave this blank to use a default, internal password.

A new, empty credentials store called credentials-store.xml is created in the directory <path>. If you chose to define your own password for the store then you will need to give this password when you perform any operation on the credentials store.

Adding data to a credentials store

Each credentials store can be used to store multiple passwords, SSL private keys, and trusted certificates.

Adding an account password

Run the credentials tool, defining the name of the credentials store to update and using the --add-userpass flag to define the details of the account. You must define an alias for each account, in addition to the user name and password. This is used to refer to the account when you are managing and using the credentials store. For example:

odasa credentials --credentials $SEMMLE_HOME/credentials-store.xml --add-userpass myAlias myUsername myPassword

where myAlias is the alias for the account with the user name myUsername and the password myPassword.

  • For details of the command syntax for the credentials tool, see the credentials reference topic.
  • The command-line examples in this topic use the Linux/OS X environment variable $SEMMLE_HOME. On Windows the equivalent environment variable is %SEMMLE_HOME%. You do not need to store the credentials store at this location, this is simply an example.

Having added this account you will be able to access the user name and password by referring to the account alias. For example, once you enable a project to use this credentials store (see details below) you can specify the user name and password in configuration files for the project by using the custom variables ${myAlias.username} and ${myAlias.password}.

Importing a trusted SSL certificate

Run the credentials tool, defining the name of the credentials store to update and using the --import-certificate flag to define the certificate to import. You must define an alias for each certificate. This is used to refer to the certificate when you are managing and using the credentials store. For example:

odasa credentials --credentials $SEMMLE_HOME/credentials-store.xml --import-certificate myAlias2 <path-to>/mycert.cer

where myAlias2 is an alias that you will use to refer to the certificate stored in <path-to>/mycert.cer.

Importing credentials from a trusted Java key store

Run the credentials tool, defining the name of the credentials store to update and using the --import-keystore flag to define the key store to import. The password for the key store may be defined using the --keystore-pass flag or entered during the import process. By default all entries are imported into the credentials store using the aliases defined in the key store. This behavior can be modified using the optional flags: --rename, and --skip. See credentials for details of all the flags supported by this tool. For example:

odasa credentials --credentials $SEMMLE_HOME/credentials-store.xml --import-keystore <path-to>/mykeystore.jks

Reporting on the stored credentials

You can check the contents of the credentials store using the --list flag. When you run the command with this flag, all aliases stored in the file are reported. For example:

odasa credentials --credentials $SEMMLE_HOME/credentials-store.xml --list

Using data from a credentials store

You can use the data in the credentials store to authenticate in any of the following ways:

  • Via variables—by modifying the variables file for a project to include details of a credentials store. You can then use variables to represent user names and passwords in the project configuration files.
  • Direct use—some commands have optional flags which can be used to interrogate the credentials store directly. 

Using variables to represent credentials

To make the contents of a credentials store available to scripts and commands as variables, you need to define the value of the semmle_credentials_file variable in the variables file for the project. 

To make credentials available to a project as variables
  1. Locate the project configuration file for the project that you want to change.
  2. If there is already a variables file in the same directory, edit this file. Otherwise, create a file called variables in this directory.
  3. Add a line to the variables file to define the location of the credentials store that you want to use. For example:

    semmle_credentials_file=<path-to>/credentials-store.xml

    The path to the credentials store file can be relative to the variables file, an absolute path, or may include a variable. For example, in the following example the Semmle built-in variable ${project} is used to represent the absolute path to the project directory for the project to which the variables file relates:

    semmle_credentials_file=${project}/credentials-store.xml

    Important

    For Microsoft Windows, note that the backslash character is the escape character, so you must enter it twice to specify a literal backslash. For example: C:\\semmle\\credentials\\credentials-store.xml

  4. If you created a credentials store with an external password then you must also define this password in the variables file, using the variable semmle_credentials_password.
  5. Save the variables file.

The user name and password for every account stored in the credentials store are available to project configuration files as: ${alias_name.username} and ${alias_name.password} respectively, where alias_name is an alias that was added to the credentials store using the --add-userpass flag of the credentials tool.

Example

In this example, you want to analyze a project, MyProject, that uses a password-protected Subversion repository. Your configuration files are stored under the main odasa directory—that is, SEMMLE_HOME is odasa .

  1. Ask the repository administrator to create you an account with read-only access to the project (in this example the user name semmle is used).
  2. Use odasa bootstrap to create a Semmle project for the MyProject code base, answering all prompts.
    When you are asked if you want to add a snapshot, answer no.
    The bootstrap tool creates a new project-specific subdirectory within the projects directory, called MyProject
  3. Create a credentials store in the projects/MyProject directory by running the following command in the main odasa directory:
    odasa credentials --create --credentials projects/MyProject/credentials-store.xml 
  4. Add the Subversion account for MyProject to the store using an alias for the account (for example, MyProject-svn):
    odasa credentials --credentials projects/MyProject/credentials-store.xml --add-userpass MyProject-svn semmle
  5. When you are prompted, enter the password for the semmle user.
  6. Check that the account details have been added correctly:
    odasa credentials --list --credentials projects/MyProject/credentials-store.xml 
    Output:

    Passwords:
      pass:MyProject-svn for: semmle
        auth scope:
          0:{ scheme:<any> host:<any> port:<any> realm:<any>}
  7. In the projects/MyProject directory, create a variables file and use the  semmle_credentials_file variable to define the location of the credentials store you created in step 3:
    semmle_credentials_file=${project}/credentials-store.xml

    The ${project} variable represents the full path to the project to which this configuration relates—see Semmle variables.

  8. Edit the project configuration file and update the checkout command to include variables for the user name and password required to check out the project from Subversion:
    <checkout>svn checkout "https://internal/repos/myproject/trunk/" --username ${MyProject-svn.username} --password ${MyProject-svn.password}  ${src}</checkout> 
  9. Use the addLatestSnapshot command to add a snapshot of the latest revision to the project and analyze as normal.