CxSAST (OData) API Overview & Examples

Overview

The CxSAST OData API enables retrieving data from the CxSAST database. Odata API returns only full scan details.

Data Consumed

The data that can currently be consumed from the CxSAST Database includes:

Projects
Scans
Results

Metadata

The $metadata is an OData service. It returns an EDMX (Entity Data Model XML) document that contains a complete description of the feeds, types, properties, and relationships exposed by the service in EDM (Entity Data Model).

For details about the actual data structure exposed by CxSAST, see http://localhost/Cxwebinterface/odata/v1/$metadata.

Authentication

The required authentication method depends on the method used by Cx Server - either Basic or Windows authentication (up to v8.9.0).

For v9.0.0 and up, token-based authentication using the new access control module is used. For more information about authentication using access control, refer to CxSAST (OData) API Authentication.

OData.Org

For further information on how to implement the functions of OData, see the OData.org website.

Examples

For a specific scan Id

Request result: retrieve all data for a specific scan Id:
Query used for retrieving the data: http://localhost/Cxwebinterface/odata/v1/Scans(1000005)

Retrieve number of LOC scanned for a specific scan:

Request result: retrieve LOC scanned value for a specific scan Id
Query used for retrieving the data: http://localhost/Cxwebinterface/odata/v1/Scans(1000005)?$select=LOC

Retrieve number of LOC scanned for all scan:

Request result: retrieve LOC scanned value for all scans
Query used for retrieving the data: http://localhost/Cxwebinterface/odata/v1/Scans?$select=LOC,Id

Top 5 Projects By Risk Score:

Requested result: list the 5 Projects whose most recent scans yielded the highest Risk Score
Query used for retrieving the data: http://localhost/Cxwebinterface/odata/v1/Projects?$expand=LastScan&$orderby=LastScan/RiskScore%20desc&$top=5

Top 5 Projects By (Last) Scan Duration:

Requested result: list the 5 Projects whose most recent scan had the longest duration
Query used for retrieving the data: http://localhost/Cxwebinterface/odata/v1/Projects?$expand=LastScan&$orderby=LastScan/ScanDuration%20desc&$top=5

All Projects with their Last Scan and the High Vulnerabilities:

Requested result: list all projects, and for each project list the security issues (vulnerabilities) with a High severity degree found in the project's most recent scan.
Query used for retrieving the data: http://localhost/Cxwebinterface/odata/v1/Projects?$expand=LastScan($expand=Results($filter=Severity%20eq%20CxDataRepository.Severity%27High%27))
Same query broken into two pages of 10 projects each:
1. http://localhost/Cxwebinterface/odata/v1/Projects?$expand=LastScan($expand=Results($filter=Severity%20eq%20CxDataRepository.Severity%27High%27))&$top=10&$skip=0
2. http://localhost/Cxwebinterface/odata/v1/Projects?$expand=LastScan($expand=Results($filter=Severity%20eq%20CxDataRepository.Severity%27High%27))&$top=10&$skip=10

For a specific Project, for the LastScan, get two pages of 10 results each:

Obtain the ProjectId either by looping through projects or via apriori knowledge (using CxWebClient or other means):
http://localhost.checkmarx.net/Cxwebinterface/odata/v1/Projects?$select=Id
Assuming that ProjectId = 4205 from previous step, get the Scanid of LastScan:
http://localhost.checkmarx.net/Cxwebinterface/odata/v1/Projects(4205)/LastScan?$select=Id
Assuming that ScanId = 1006992 from previous step, get the Results in two pages of 10 results each:
1. http://localhost.checkmarx.net/Cxwebinterface/odata/v1/Scans(1006992)/Results?$top=10&$skip=0
2. http://localhost.checkmarx.net/Cxwebinterface/odata/v1/Scans(1006992)/Results?$top=10&$skip=10

Only projects that have high vulnerabilities (in the Last Scan):

Requested result:list only projects that had vulnerabilities with a High severity degree found in their last scan
Query used for retrieving the data: http://localhost/Cxwebinterface/odata/v1/Projects?$expand=LastScan($expand=Results)&$filter=LastScan/Results/any(r:%20r/Severity%20eq%20CxDataRepository.Severity%27High%27)

For a specific project, retrieve all scans within a predefined time range and their H/M/L values:

Requested result:list all scans carried out in a specific project within a predefined time range, as well as their H/M/L (High/Medium/Low) values. The sample query below refers to a time range between the 23/07/2015 and 23/08/2015.
Query used for retrieving the data: http://localhost/Cxwebinterface/odata/v1/Projects(11)/Scans?$filter=ScanRequestedOn%20gt%202015-07-23%20and%20ScanRequestedOn%20lt%202015-08-23&$select=Id,ScanRequestedOn,High,Medium,Low&$orderby=ScanRequestedOn%20desc

For all projects in a team, return the number of recurrent/resolved/new issues (vulnerabilities) within a predefined time range:

Requested result:list the number of recurrent/resolved/new issues (vulnerabilities) detected by scans made in all projects that were carried out in a team within a predefined time range. The sample query below refers to a time range between the 23/07/2015 and 23/08/2015.
Query used for retrieving the data: http://localhost/Cxwebinterface/odata/v1/Projects?$filter=OwningTeamId%20eq%20%2700000000-1111-1111-b111-989c9070eb11%27&$expand=Scans($expand=ResultSummary;$select=Id,ScanRequestedOn,ResultSummary;$filter=ScanRequestedOn%20gt%202015-07-23%20and%20ScanRequestedOn%20lt%202015-08-23)

For a specific project, the state of each scan result for a specific project since a specific date:

Requested result: for a specific project, list all the scans starting from a specific date, and for each scan retrieve three parameters (Id, ScanId, and StateId) as well as the state of each of the scan's vulnerabilities that was found in scans since the specified date.
Query used for retrieving the data: http://localhost/Cxwebinterface/odata/v1/Scans?$filter=ProjectId%20eq%2011%20and%20ScanRequestedOn%20gt%202014-12-31&$expand=Results($expand=State;$select=Id,ScanId,StateId)

Retrieve a count (not in JSON format) of the projects in the system:

Query used for retrieving the data: http://localhost/Cxwebinterface/odata/v1/Projects/$count

Retrieve all projects with a custom field that has a specific value:

Requested result: retrieve all projects that contain a custom filed (for example, ProjManager, indicating the project manager's name) with a specific value (for example, Joe).
Query used for retrieving the data:http://localhost/Cxwebinterface/odata/v1/Projects?$filter=CustomFields/any(f: f/FieldName eq 'ProjManager' and f/FieldValue eq 'Joe')

Retrieve all projects with a custom field, as well as the custom field's information:

Requested result: retrieve all projects that contain a custom field (for example, ProjManager, indicating the project manager's name), as well as the custom field's information.

Query used for retrieving the data: http://localhost/cxwebinterface/odata/v1/Projects?$expand=CustomFields&$filter=CustomFields/any(f: f/FieldName eq 'Field1')

Retrieve the query (SQL Injection, etc.) that was run for a particular unique scan result:

Requested result: selects a particular unique scan result and lists the query (SQL Injection, etc.) that was run
Query used for retrieving the data: http://localhost/Cxwebinterface/odata/v1/Results(Id=18,ScanId=1000001)?$expand=Query($select=Name)

Retrieve a list of presets associated with each project:

Requested result: retrieves a list of presets associated with each project
Query used for retrieving the data: http://localhost/Cxwebinterface/odata/v1/Projects?$expand=Preset

Retrieve all projects that are set up with a non-standard configuration:

Requested result: retrieve all projects that are set up with a non-standard configuration, such as “Multi-Lanaguage Scan (v8.4.2 and up)".
Query used for retrieving the data: http://localhost/Cxwebinterface/odata/v1/Projects?$filter=EngineConfigurationId or http://localhost/Cxwebinterface/odata/v1/Projects?$filter=EngineConfigurationId%20gt%201

Possible Issues

The following issues can occur when working with OData:

The default value of the timeout parameter can be too low when executing highly complex queries. For details, see the Troubleshooting section OData Commands Time Out.
The process may run out of memory after consuming the .NET 4GB of memory. For details, see the Troubleshooting section .NET Memory Limit Exceeded.

Extending Timeout

The timeout parameter defines how long the code waits for SQL to execute the query.

While simple queries can be executed successfully and free the database within the limits of a low timeout value, such a low value can cause highly complex queries to fail, resulting in an http 400 status (Bad Request) message. This message notifies that the query execution has timed out.

When such a message is received, users should first ensure that the queries are fine-tuned and do not unnecessarily load the system. If all fine-tuning efforts do not yield the requested timeout decrease, users can enable handling complex queries by modifying the OData command timeout parameter. This parameter is set through the key specified below, whose default value is 120 seconds.

CxComponentConfiguration Table

The record with [Key] = 'ODATA_COMMAND_TIMEOUT'

.NET Memory Limit Exceeded

When a command does not time out but the .NET 4GB of memory runs out, the user receives the following response with an http 400 status (Bad Request):

"The result is too large to return, the process ran out of memory. Try requesting paged data or refining your search".

Solution:

When retrieving large data quantities, it is recommended to use OData in paging mode. This significantly reduces the initial response time, thereby preventing overload on the CX server machine.

http://www.odata.org/documentation/odata-version-2-0/uri-conventions/

Request broken into two pages of 10 projects each:

http://localhost/Cxwebinterface/odata/v1/Projects?$expand=LastScan($expand=Results($filter=Severity%20eq%20CxDataRepository.Severity%27High%27))&$top=10&$skip=0
http://localhost/Cxwebinterface/odata/v1/Projects?$expand=LastScan($expand=Results($filter=Severity%20eq%20CxDataRepository.Severity%27High%27))&$top=10&$skip=10