How to use the API to identify vulnerability and route coverage data within a session

Objective

Retrieve application vulnerability and route coverage data associated with a given session via the Contrast API.

Process

New APIs were created as of the 3.9.7 and 3.9.8 releases for users to more easily identify application vulnerability and route coverage data associated with a given session. Recall a session requires session metadata to be set.

• Lookup session by metadata: /ng/organizations/{orgUuid}/applications/{appId}/agent-sessions/filter (POST)
• Get most recent session: /ng/organizations/{orgUuid}/applications/{appId}/agent-sessions/latest (GET)
• Filter application vulnerabilities by agentSessionId: /ng/{orgUuid}/traces/{appId}/filter (POST)
• Pull route coverage metrics by agentSessionId: /ng/{orgUuid}/applications/{appId}/route (GET)

Ultimately, to return vulnerabilities or route data by session, a user needs the agentSessionId. The IDs can be returned by using the first call or the second call. The first call returns all sessions that correspond to the given session metadata values. Note the user must append the metadata label and values as shown below:

% curl -X POST
'https://apptwo.contrastsecurity.com/Contrast/api/ng/organizations/3c3a73d6-78a0-46c7-944a-b07b94d557f1/applications/2a0b1763-9314-4b55-a946-031d2741d628/agent-sessions/filter' \
    -HAccept:application/json \
    -HContent-Type:application/json \
    -HAuthorization:REDACTED \
    -HAPI-Key:REDACTED \
    -d '{"metadata": [
        {"label": "branchName", "values": ["test-branch"]},
        {"label": "committer", "values": ["Some Dev", "Another Dev"]}
        ]}'

The second call returns the most recent session. It requires no filters. See below:

% curl -X GET
'https://apptwo.contrastsecurity.com/Contrast/api/ng/organizations/3c3a73d6-78a0-46c7-944a-b07b94d557f1/applications/2a0b1763-9314-4b55-a946-031d2741d628/agent-sessions/latest' \
    -HAccept:application/json \
    -HAuthorization:REDACTED \
    -HAPI-Key:REDACTED

Using the agentSessionId, the user can filter the route or vulnerability calls to return data only for that session. These APIs enable easier access to session-based data, which in turn allows users to gate builds or conduct other analyses based on data specific to that build.