Issue/Question

How can we use 42Crunch API endpoints to get the progress of the API Conformance Scan and its result?

Solution/Answer

If you call the endpoint below:

<platform_URL>/api/v1/apis/<api_uuid> 

Using platform.42crunch.com as an example for platform_URL

Use the following example that utilizes a session ID:

curl -X GET https://platform.42crunch.com/api/v1/apis/8xxxxxxx-1xxx-4xxx-9xxx-7xxxxxxxxxxx -H "Cookie: sessionid=2xxxxxxx-1xxx-4xxx-bxxx-2xxxxxxxxxxx"

Use the following example that utilizes an API Token:

curl -X GET https://platform.42crunch.com/api/v1/apis/8xxxxxxx-1xxx-4xxx-9xxx-7xxxxxxxxxxx -H "X-API-KEY: api_2xxxxxxx-3xxx-4xxx-5xxx-6xxxxxxxxxxx"

{
    "desc": {
        "id": "8xxxxxxx-1xxx-4xxx-9xxx-7xxxxxxxxxxx",
        "cid": "9xxxxxxx-2xxx-4xxx-8xxx-7xxxxxxxxxxx",
        "name": "API_Name",
        "technicalName": "8xxxxxxx-1xxx-4xxx-9xxx-7xxxxxxxxxxx",
        "specfile": "",
        "yaml": false,
        "revisionOasCounter": 0,
        "lock": false,
        "lockReason": ""
    },
    "revision": {
        "id": "4xxxxxxx-dxxx-4xxx-8xxx-dxxxxxxxxxxx",
        "aid": "8xxxxxxx-1xxx-4xxx-9xxx-7xxxxxxxxxxx",
        "createAt": "2022-09-06T20:44:10Z",
        "taskId": "",
        "revisionNumber": "0",
        "revisionVersion": "",
        "revisionDate": "1970-01-01T00:00:00Z",
        "SecuredRevisionOasCounter": "0",
        "parentId": "",
        "yaml": false,
        "oasFile": "",
        "readSpecFile": false
    },
    "assessment": {
        "isProcessed": true,
        "last": "2022-10-03T14:39:24Z",
        "error": false,
        "errors": {},
        "isValid": true,
        "grade": 89.27491666666667,
        "numErrors": 9,
        "numInfos": 1,
        "numLows": 0,
        "numMediums": 8,
        "numHighs": 0,
        "numCriticals": 0,
        "oasVersion": "2.0",
        "releasable": false,
        "sqgPass": true,
        "auditVersion": "3.1.4"
    },
    "scan": {
        "isProcessed": true,
        "last": "2022-10-05T10:52:10Z",
        "numHighs": 0,
        "numMediums": 0,
        "numLows": 36,
        "state": "finished",
        "exitCode": 0,
        "requestDone": 42,
        "mode": 1,
        "sqgPass": true,
        "scanVersion": "1.22.1"
    },
    "protection": {
        "isProcessed": true,
        "last": "2022-09-06T20:44:40Z",
        "lastCompilation": "2022-09-06T20:44:40Z",
        "compilationStatus": true,
        "numActiveClients": 1
    },
    "tags": []
}

If you check the scan section in the JSON output, you will see if the conformance scan has been completed by the isProcessed object, as well as a few details about said scan.

Here's some additional info each of the objects in the mentioned section:

"scan": {
        "isProcessed": true,                   => Scan report available
        "last": "2022-08-16T16:18:06Z",        => Scan last ran at
        "numHighs": 0,                         => Number of high severity issues
        "numMediums": 0,                       => Number of medium severity issues
        "numLows": 42,                         => Number of low severity issues
        "state": "finished",                   => Scan process status
        "exitCode": 0,                         => Scan exit code, 0 means OK
        "requestDone": 50,                     => Total number of injections done
        "mode": 1,                             => Scan type, 1=SaaS 2=On-Premises
        "sqgPass": false,                      => Scan SQG status
        "scanVersion": "1.21.0"                => Scan Version
    }

Scan exit codes can be as below:

0 Ok
1 The OAS file given is not valid. Need to run the assessment before
2 The configuration file is not valid according the specification
3 The API is not reachable, a reason can be that the API is not up or a network issue
4 The OAS file given is too complex to be processed
5 Too many issues in the scan report
6 Too many timeouts/connection closed by the API, reason can be a crash in the API side or network issue
7 Maximum memory reached by the scan process
8 Maximum size reached for the report
9 Maximum scan time reached

sqgPass object is whether or not the SQG associated with the conformance scan is passed or failed. Its state can be null, finished, blocked.

To get the SaaS scan report, you would hit the following endpoint:

<platform_URL>/api/v1/apis/<api_uuid>/scanreport?medium=1

To get the on-prem scan report, you would hit the following endpoint:

<platform_URL>/api/v1/apis/<api_uuid>/scanreport?medium=2

The data object contains a base64 encoded report.  If you get a 404 on either URL, there is no report available.