veracode/api-signing repository overview

⁠Veracode API Signing

The Veracode integrations and APIs use Hash-based Message Authentication Code (HMAC) to provide added security when accessing API resources. You are required to provide Veracode API credentials, which consist of an API ID and key. The APIs use these credentials to digitally sign the HTTP header with HMAC. The Veracode APIs require HMAC authentication in Python applications to provide these security measures:

• Credentials are not sent as plain text. The API key is never transmitted, but encrypts the HMAC at the client-side and decrypts it at the server-side.
• The HMAC signature validates that the message was not tampered with or altered in transit. Any change to the message invalidates the HMAC.
• The HMAC signature includes a nonce (one-time code) that prevents replay attacks.
• You can revoke and regenerate the Veracode API credentials to respond to an accidental credentials leak.

Using this Docker Hub image enables you to “sign” an API request with an HMAC digest. For information about HMAC authentication and examples of how to use this API signing library, visit the Veracode Help Center⁠.

⁠Image Details

There are two variants:

• veracode/api-signing
  The environment variant for when you want a shell. This is probably what you want for pipelines or other situations where you need a shell. The latest tag is applied to this variant.
• veracode/api-signing:cmd The command variant is for when you just want to run http with veracode_hmac authentication from the command line and is useful when run via shell aliases.

The images are built on the python⁠ Docker Official Images. By default containers run as a non-privileged, local user.

⁠Running as an Environment

In a GitLab pipline:

# This job assumes Veracode API credentials have been set as group or
# project variables named VERACODE_API_KEY_ID and VERACODE_API_KEY_SECRET
check_credentials:
    image: veracode/api-signing
    script:
      - http --auth-type veracode_hmac https://api.veracode.com/api/authn/v2/api_credentials

For a local shell with current host OS directory mounted inside the container:

docker run -it --rm -v $PWD:/home/luser veracode/api-signing /bin/bash

By default containers run as a non-privileged, local user in /home/luser. If needed, you can override these defaults. You can get a root shell with the --user argument and change the working directory with the --workdir argument:

docker run -it --rm --user root veracode/api-signing /bin/bash
docker run -it --rm --workdir /my/app/path veracode/api-signing /bin/bash
docker run -it --rm --user root --workdir /my/app/path veracode/api-signing /bin/bash

⁠Running as a Command

Running HTTPie (http) with Veracode HMAC Authentication using a Veracode Credentials⁠ file mounted into the container:

docker run -it --rm \
    -v ~/.veracode/credentials:/home/luser/.veracode/credentials \
    veracode/api-signing:cmd \
        https://api.veracode.com/api/authn/v2/api_credentials

docker run -it --rm \
    -v ~/.veracode/credentials:/home/luser/.veracode/credentials \
    veracode/api-signing:cmd \
        https://api.veracode.com/appsec/v1/applications \
        name==veracode-api-signing

Running http with API credentials provided as environment variables:

docker run -it --rm \
    --env VERACODE_API_KEY_ID=c2db7664... \
    --env VERACODE_API_KEY_SECRET=24f62c81... \
    veracode/api-signing:cmd \
        https://api.veracode.com/appsec/v1/applications \
        business_unit==Product%20Security

⁠Aliases

The command variant is particularly useful when run via a shell alias:

alias 'veracode-http'='docker run -it --rm -v $PWD:/home/luser -v ~/.veracode/credentials:/home/luser/.veracode/credentials veracode/api-signing:cmd'

Then the container can be run as if it were a locally installed executable:

veracode-http --help
veracode-http https://api.veracode.com/appsec/v1/applications name==MyApplication
veracode-http --pretty none --body https://api.veracode.com/api/authn/v2/api_credentials | jq '.expiration_ts'