Fortify Software Security Center (SSC) RESTFul API Python Client

Common errors

• SSLError: CERTIFICATE_VERIFY_FAILED

  cause The Python environment cannot verify the SSL certificate presented by the Fortify SSC host, often due to self-signed certificates or missing CA certificates.
  fix For development/testing, you can disable SSL verification by passing `verify_ssl=False` to the `FortifyApi` constructor. For production, ensure your Fortify SSC instance uses a trusted certificate and that your client system has the necessary CA certificates installed and trusted.

• AttributeError: module 'fortifyapi' has no attribute 'FortifyApi'

  cause Attempting to import `FortifyApi` directly from the top-level `fortifyapi` package instead of its `fortify` submodule.
  fix Change the import statement to `from fortifyapi.fortify import FortifyApi`.

• API response indicates 401 Unauthorized or 'Failed to retrieve Fortify SSC API token.'

  cause Incorrect username/password, expired/invalid API token, or insufficient permissions for the user/token used to connect to Fortify SSC.
  fix Double-check your `FORTIFY_SSC_HOST`, `FORTIFY_SSC_USER`, and `FORTIFY_SSC_PASSWORD` environment variables or credentials. Ensure the user or token has the necessary permissions in Fortify SSC for the operations being attempted.

• Error 404 Not Found when accessing an API endpoint.

  cause The requested API endpoint does not exist, the URL path is incorrect, or the endpoint has been deprecated/removed in the version of Fortify SSC being targeted.
  fix Verify the exact API endpoint path against your Fortify SSC version's API documentation. If using an older `fortifyapi` version, check for changes in the SSC API that might require updating your code and the library.

Warnings

• breaking Fortify SSC (the backend API) has deprecated and removed several API endpoints. Notably, `/api/v1/auth/token` was replaced by `/api/v1/tokens` and the SOAP API is deprecated. Using older `fortifyapi` versions with newer SSC instances, or code relying on old endpoints, will break.
  Fix: Upgrade your `fortifyapi` library to the latest version and update your code to use the newer SSC API endpoints, such as `/api/v1/tokens` for authentication. Consult Fortify SSC release notes for API migration guides.
• gotcha Fortify SSC 21.2.0+ no longer explicitly announces Basic HTTP authentication on REST API endpoints via the `WWW-Authenticate` header. Clients *must* explicitly add the `Authorization` header.
  Fix: Ensure your authentication mechanism (e.g., `fortifyapi`'s `username`/`password` or `token` parameters) correctly provides the `Authorization` header. If implementing custom authentication logic, explicitly set the `Authorization` header.
• gotcha Fortify SSC API calls may be subject to rate limiting and JSON payload size limits. Exceeding these limits can result in `429 Too Many Requests` or errors for large bulk operations.
  Fix: Implement retry logic with exponential backoff for `429` responses. For bulk operations, break down large JSON payloads into smaller requests to stay within the 10 MB limit for JSON submitted to SSC.

Install

• pip install fortifyapi Install stable version

Imports

• FortifyApi
  wrong:

  import fortifyapi

  correct:

  from fortifyapi.fortify import FortifyApi

  The primary API client class is within the 'fortify' submodule.

Quickstart

This quickstart demonstrates how to authenticate with Fortify SSC using username/password to obtain an API token, then use that token to list all available project versions. Remember to configure your Fortify SSC host, username, and password, preferably via environment variables, and handle SSL verification appropriately for your environment.

import os
from fortifyapi.fortify import FortifyApi

# Set environment variables for connection
FORTIFY_SSC_HOST = os.environ.get('FORTIFY_SSC_HOST', 'https://localhost:8443/ssc')
FORTIFY_SSC_USER = os.environ.get('FORTIFY_SSC_USER', 'your_ssc_username')
FORTIFY_SSC_PASSWORD = os.environ.get('FORTIFY_SSC_PASSWORD', 'your_ssc_password')

def get_ssc_token():
    """Authenticates with SSC and retrieves an API token."""
    # Bypass SSL verification if you have issues with self-signed certs (NOT recommended for production)
    ssc_client = FortifyApi(host=FORTIFY_SSC_HOST, username=FORTIFY_SSC_USER, 
                            password=FORTIFY_SSC_PASSWORD, verify_ssl=False)
    response = ssc_client.get_token(description='fortifyapi_client_token')
    if response.data and 'data' in response.data and 'token' in response.data['data']:
        return response.data['data']['token']
    raise Exception("Failed to retrieve Fortify SSC API token.")

def list_project_versions():
    """Lists all project versions in Fortify SSC."""
    try:
        token = get_ssc_token()
        ssc_client = FortifyApi(host=FORTIFY_SSC_HOST, token=token, verify_ssl=False)
        response = ssc_client.get_all_project_versions()
        if response.data and 'data' in response.data:
            print("Fortify SSC Project Versions:")
            for version in response.data['data']:
                print(f"  ID: {version['id']}, Project: {version['project']['name']}, Version: {version['name']}")
        else:
            print("No project versions found or API response was empty.")
    except Exception as e:
        print(f"An error occurred: {e}")

if __name__ == '__main__':
    # Make sure to set FORTIFY_SSC_HOST, FORTIFY_SSC_USER, FORTIFY_SSC_PASSWORD
    # environment variables or replace placeholders for actual usage.
    list_project_versions()