Skip to main content

APIs

The Checkmarx Reporting Service serves an API that allows generating reports, checking their status, and retrieving them once they are available.

The following endpoints are available:

  • POST api/reports for Report Creation.

  • GET api/reports/{id}/status to get Report Status.

  • GET api/reports/{id} for the Report Retrieval.

Notice

The Swagger documentation is currently unavailable.

Create Reports

Parameters

The following parameters should be defined when requesting a report:

  • templateId: Unique ID of a specific Template. Possible Values are:

    • 1 for Scan Template Vulnerability Type oriented

    • 2 for Scan Template Result State oriented

    • 3 for Project Template

    • 4 for Single Team Template

    • 5 for Multi Teams Template

    • 6 for Application Template

    • 7 for Executive Template

  • entityId: Unique ID. Possible Values:

    • For the Scan template: Scan Id

    • For the Project template: Project Id

    • For the Single Team template: Team full name

    • For the Multiple Teams template: list of Teams full name split by comma

    • For the application template: list of project Id split by comma

  • reportName: Name of the report to be generated. The service generates automatically a report Id that will be concatenated with the specified report name.

  • filters: Filters to be applied in the report creation.

    • Severity ("type": 1)

      Build based on excludedValues.

      If not defined, Low and Informative results are excluded by default.

      Applicable for all report types.

    • Result State ("type": 2)

      Build based on excludedValues.

      If not defined, none is excluded by default.

      Custom result states can also be defined as excludedValues. If not defined, these are included as part of the report.

      Applicable for all report types.

    • Query/Vulnerability ("type": 3)

      Build based on excludedValues.

      If not defined none is excluded by default.

      Applicable for the Scan Template only.

    • Timeframe ("type": 4)

      Build based on includedValues.

      To define a date range composed by a starting and an ending date, in the format yyyy-MM-dd

      Applicable for all report types with the exception of the Scan Template.

    • Status ("type": 5)

      Build based on excludedValues.

      If not defined, Resolved is excluded by default.

      Applicable for all report types.

    • Results Limit ("type": 6)

      Build based on includedValues, 5000 is the default limit.

      Applicable for the Scan Template only.

    • Data Point ("type": 7)

      Build based on includedValues.

      By default last is used as data point.\n\n Allowed values are last or first.

      Applicable for all report types with the exception of the Scan Template.

    • Project Name ("type": 8)

      Build based on excludedValues.

      If not defined none is excluded by default.

      Applicable for Teams and Executive templates.

    • Project Custom Fields ("type": 9)

      Build based on includedValues.

      If not defined no project is excluded by default.

      Applicable for Teams, Application and Executive templates.

  • metadata: to include additional details for specific KPIs. For further details please see Metadata.

    • TeamFullName, available for the Scan, Project, Team(s) and Application templates.

    • ScanComments, available for the Scan template.

    • ScanCustomFields, available for the Scan template.

    • ProjectBranchInformation, available in the Project, Single Team and Application templates.

Examples on how to create reports

Scan Report, Vulnerability Type oriented

Filters not defined

  1. template Id = 1.

  2. entityId is the Scan Id.

  3. report_name = “scan_report“ which means that final name will be <generated_report_id>_scan_report.pdf

  4. Filters are not defined meaning that:

    1. High and Medium will be included by default; Low and Information excluded by default.

    2. All available Result states will be included by default.

    3. Only New and Recurrent will be included by default. Resolved results will be excluded.

    4. All Vulnerability Types will be included by default.

    5. The maximum results displayed in Scan Results section will be 5000.

{
  "templateId": 1,
  "entityId": ["1010169"],  
  "reportName": "scan_report", 
  "filters": [],
  "outputFormat": "PDF" 
}
excludedValues not defined

  1. template Id = 1.

  2. entityId is the Scan Id.

  3. Following filters defined as "excludedValues": [ ], meaning that None is excluded:

    1. All severities are included.

    2. All Result States are included.

    3. All Vulnerability Types will be included by default.

    4. All available status will be included by default.

{
  "templateId": 1,
  "entityId": ["1010169"],  
  "reportName": "scan_report", 
  "filters": [
{
  "type": 1, 
  "excludedValues": []
},
{
  "type": 2, 
  "excludedValues": [ ]
},
{
  "type": 3,
  "excludedValues": [ ]
},
{
  "type": 5,
  "excludedValues": []
}
  ],
  "outputFormat": "PDF" 
}
Defining excludedValues and includedValues

  1. template Id = 1.

  2. entityId is the Scan Id.

  3. Excluding Low and Information

    1. For filter by Severity use type = 1

  4. Excluding Not Exploitable

    1. For filter by Result State use type = 2

  5. Excluding SQL Injection

    1. To apply filters by Query use type = 3

  6. Excluding New findings

    1. To apply filters by Status use type = 5

  7. Including the Limit Results to be printed in Scan Results section to 100

{
  "templateId": 1,
  "entityId": ["1010169"],
  "reportName": "Scan_report",
  "filters": [
    {
      "type": 1,
      "excludedValues": [
        "Low", "Information"
      ]
    },
    {
      "type": 2,
      "excludedValues": [
        "Not Exploitable"
      ]
    },
    {
      "type": 3,
      "excludedValues": [
        "SQL_Injection"
      ]
    },
    {
      "type": 5,
      "excludedValues": [
        "New"
      ]
    },
    {
       "type": 6,
      "includedValues": [ "100" ]
    }
  ],
  "outputFormat": "PDF"
}

Scan Report, Result State oriented

Filters not defined

  1. template Id = 2.

  2. entityId is the Scan Id.

  3. Filters are not defined meaning that:

    1. High and Medium will be included by default; Low and Information excluded by default.

    2. All available Result states will be included by default.

    3. Only New and Recurrent will be included by default. Resolved results will be excluded.

    4. All Vulnerability Types will be included by default.

    5. The maximum results displayed in Scan Results section will be 5000.

{
  "templateId": 2,
  "entityId": ["1010169"],  
  "reportName": "scan_report", 
  "filters": [],
  "outputFormat": "PDF" 
}
With metadata defined

Metadata defined for TeamFullName and ScanComments

{
  "templateId": 2,
  "entityId": ["1010169"],  
  "reportName": "scan_report", 
  "filters": [],
  "outputFormat": "PDF",
  "includedMetadata": ["TeamFullName", "ScanComments"]
}

Project Report

  1. templateId = 3.

  2. entityId is the Project Id.

  3. report_name = “project_report“ which means that final name will be <generated_report_id>_project_report.pdf

  4. Excluding results having severity = Information.

  5. Setting type = 2 as "excludedValues": [ ], meaning that none Result state will be excluded.

  6. Setting timeframe with included values between July 9 and July 13.

  7. Setting data point as first.

  8. Filter for Status not defined meaning that New and Recurrent will be included by default. Resolved results will be excluded.

{
  "templateId": 3,
  "entityId": ["75"],  
  "reportName": "project_report", 
  "filters": [
    {
      "type": 1,  
      "excludedValues": [ "Information" ]
    },
    {
      "type": 2, 
      "excludedValues": []
    },
    {
      "type": 4,
      "includedValues": [ 
          "2021-07-09", 
          "2021-07-13" 
        ]
    },
    {
      "type": 7, 
      "includedValues": ["first"]
    }
  ],
  "outputFormat": "PDF" 
}

Single Team report

Filters not defined

  1. template Id = 4.

  2. entityId is the Team Name.

  3. Filters are not defined meaning that:

    1. All Project belonging to the team are included with all custom fields.

    2. High and Medium will be included by default; Low and Information excluded by default.

    3. All available Result states will be included by default.

    4. Only New and Recurrent will be included by default. Resolved results will be excluded.

    5. Last Scan is used as data point.

    6. Projects lifetime is used as timeframe.

{
"templateId": 4,
"entityId": ["CxServer"],
"reportName": "Team_report",
"filters": [],
"outputFormat": "PDF"
}
Defining excludedValues and includedValues

  1. templateId = 4.

  2. entityId is the Path to the Team Name.

  3. report_name = “Team_report“ which means that final name will be <generated_report_id>_Team_report.pdf

  4. Excluding results having severity = Information.

  5. Setting type = 2 as "excludedValues": [“Not Exploitable“], meaning that Not Exploitable Result state will be excluded.

  6. Setting timeframe with included values between January 1 and November16.

  7. Setting type = 5 as "excludedValues": [ ], meaning that none Status will be excluded and New, Recurrent, Resolved results will be included.

  8. Setting “BookStoreJava“ as a project to exclude (type = 8).

  9. Including only project having the Custom Field called Version with value equals to 1.

{
"templateId": 4,
"entityId": ["CxServer/Java"],
"reportName": "Team_report",
"filters": [
  {
    "type": 1, 
    "excludedValues": ["Information"]
  },
  {
  "type": 2, 
  "excludedValues": ["Not Exploitable"]
  },
  {
    "type": 4,
    "includedValues": ["2021-01-01", 
          "2021-11-16" ]
  },
  {
    "type": 5,
    "excludedValues": [ ]
  },
  {
    "type": 8,
    "excludedValues": ["BookStoreJava"]
  },
  {
    "type": 9,
    "includedValues": ["Version","1"]
  }
],
"outputFormat": "PDF"
}

Multiple Teams report

Filters not defined

  1. template Id = 5.

  2. entityId is the a list of teams separated by comma.

{
"templateId": 5,
"entityId": ["CxServer/Java", "CxServer/Mobile"],
"reportName": "Team_report",
"filters": [],
"outputFormat": "PDF"
}

Application report

Defining excludedValues and includedValues

  1. templateId = 6.

  2. entityId is a list of project Id separated by comma.

  3. report_name = “Application_report“ which means that final name will be <generated_report_id>_Application_report.pdf

  4. Excluding results having severity = Information and Low.

  5. Setting type = 2 as "excludedValues": [“Not Exploitable“], meaning that Not Exploitable Result state will be excluded.

  6. Setting timeframe with included values between January 1 and November16.

  7. Setting type = 5 as "excludedValues": [ ], meaning that none Status will be excluded and New, Recurrent, Resolved results will be included.

  8. Setting data point as first (type = 7).

  9. Including only project having the Custom Field called Version with value equals to 1.

{
"templateId": 6,
"entityId": ["69", "70"],
"reportName": "Application_report",
"filters": [
  {
    "type": 1,
    "excludedValues": ["Information", "Low"]
  },
  {
    "type": 2,
    "excludedValues": ["Not Exploitable"]
  },
  {
    "type": 4,
    "includedValues": ["2021-01-01","2021-11-16" ]
  },
  {
    "type": 5,
    "excludedValues": [ ]
  },
  {
    "type": 7, 
    "includedValues": ["first"]
  },
  {
    "type": 9,
    "includedValues": ["Version","1"]
  }
],
"outputFormat": "PDF"
}

Executive report

Defining excludedValues

  1. templateId = 7.

  2. entityId is the a list of teams separated by comma.

  3. Excluding results having severity = Information .

  4. Setting timeframe with included values between January 1 and November16.

  5. Setting type = 5 as "excludedValues": [ ], meaning that none Status will be excluded and New, Recurrent, Resolved results will be included.

{
"templateId": 7,
"entityId": ["CxServer/Java", "CxServer/Mobile"],
"reportName": "Executive_report",
"filters": [
  {
    "type": 1, 
    "excludedValues": ["Information"]
  },
  {
    "type": 4,
    "includedValues": ["2021-01-01", 
          "2021-11-16" ]
  },
  {
    "type": 5,
    "excludedValues": [ ]
  }
],
"outputFormat": "PDF"
}
In this section: