Success Metrics Data REST API

The Success Metrics Data REST API returns policy evaluation, violation and remediation data, aggregated monthly or weekly. This API is available via a POST resource:

POST api/v2/reports/metrics

Note

Larger data sets may take considerable time to load the first time you access Success Metrics Data. It is recommended to generate the aggregations first by creating and loading a Success Metrics report for the desired applications and organizations.Success Metrics

Request

Content-Type: application/json

Accept header: application/json (for response in JSON format) OR text/csv (for response in csv format.)

Request format for JSON response

curl -u <username>:<password> -X POST http://localhost:8070/api/v2/reports/metrics -H "Content-Type: application/json" -H "Accept: application/json" -d "{\"timePeriod\": \"MONTH\", \"firstTimePeriod\": \"<yyyy-mm>\", \"lastTimePeriod\": \"<yyyy-mm>\", \"applicationIds\": [], \"organizationIds\": [\"<orgId>\"]}" -o "<filename.json>"

Request format for csv response

curl -u <username>:<password> -X POST http://localhost:8070/api/v2/reports/metrics -H "Content-Type: application/json" -H "Accept: text/csv" -d "{\"timePeriod\": \"MONTH\", \"firstTimePeriod\": \"<yyyy-mm>\", \"lastTimePeriod\": \"<yyyy-mm>\", \"applicationIds\": [], \"organizationIds\": [\"<orgId>\"]}" -o "<filename.csv>"

Request body

{
  // "MONTH" or "WEEK"
  "timePeriod": "MONTH",

// If timePeriod is MONTH - an ISO 8601 year and month without timezone.
  // If timePeriod is WEEK  - an ISO 8601 week year and week (e.g. week of 29 December 2008 is "2009-W01").
  "firstTimePeriod": "2018-08",

// Same rules as above. Must be equal to or after firstTimePeriod. Can be omitted,
  // in which case data for all successive time periods is provided including partial data for the current one.
  "lastTimePeriod": "2018-08",

// If both of these are null or empty, data for all applications (that the user has access to) is returned.
  // applicationIds are Internal ids.
  "applicationIds": [],
  "organizationIds": []
}

Note

Application ids are internal ids. Internal application ids can be retrieved using Application REST APIs (see Step 5).

Organization ids can be retrieved using Organization REST APIs.

Response JSON

Response JSON

[{\
  "applicationId": "foo",\
  "applicationPublicId": "asdf",\
  "applicationName": "Foo",\
  "organizationId": "bar",\
  "organizationName:" "Bar",\
\
  // Aggregations are sorted chronologically.\
  "aggregations": [{\
\
    // ISO 8601 date.\
    "timePeriodStart": "2018-08-01",\
\
    "evaluationCount": 0,\
\
    // Mean Time to Resolution (MTTR) in milliseconds.\
    "mttrLowThreat": 0,\
    "mttrModerateThreat": 0,\
    "mttrSevereThreat": 0,\
    "mttrCriticalThreat": 0,\
\
    "discoveredCounts": ViolationCountJSON,\
    "fixedCounts": ViolationCountJSON,\
    "waivedCounts": ViolationCountJSON,\
\
    // Number of unresolved violations at the end of the aggregation period.\
    "openCountsAtTimePeriodEnd": ViolationCountJSON\
  }]\
}]

ViolationCountJSON

{
  "SECURITY": {
    "LOW": 0,
    "MODERATE": 0,
    "SEVERE": 0,
    "CRITICAL": 0
  },
  "LICENSE": {
    "LOW": 0,
    "MODERATE": 0,
    "SEVERE": 0,
    "CRITICAL": 0
  },
  "QUALITY": {
    "LOW": 0,
    "MODERATE": 0,
    "SEVERE": 0,
    "CRITICAL": 0
  },
  "OTHER": {
    "LOW": 0,
    "MODERATE": 0,
    "SEVERE": 0,
    "CRITICAL": 0
  }
}

Response CSV

A CSV document containing all of the fields in the Response JSON, with one row per aggregation. Rows from the same application are grouped together and ordered chronologically. A row of column headers is included at the beginning of the file.

CSV fields

applicationId
applicationPublicId
applicationName
organizationId
organizationName

timePeriodStart

evaluationCount

mttrLowThreat
mttrModerateThreat
mttrSevereThreat
mttrCriticalThreat

discoveredCountSecurityLow
discoveredCountSecurityModerate
discoveredCountSecuritySevere
discoveredCountSecurityCritical
discoveredCountLicenseLow
discoveredCountLicenseModerate
discoveredCountLicenseSevere
discoveredCountLicenseCritical
discoveredCountQualityLow
discoveredCountQualityModerate
discoveredCountQualitySevere
discoveredCountQualityCritical
discoveredCountOtherLow
discoveredCountOtherModerate
discoveredCountOtherSevere
discoveredCountOtherCritical

fixedCountSecurityLow
fixedCountSecurityModerate
fixedCountSecuritySevere
fixedCountSecurityCritical
fixedCountLicenseLow
fixedCountLicenseModerate
fixedCountLicenseSevere
fixedCountLicenseCritical
fixedCountQualityLow
fixedCountQualityModerate
fixedCountQualitySevere
fixedCountQualityCritical
fixedCountOtherLow
fixedCountOtherModerate
fixedCountOtherSevere
fixedCountOtherCritical

waivedCountSecurityLow
waivedCountSecurityModerate
waivedCountSecuritySevere
waivedCountSecurityCritical
waivedCountLicenseLow
waivedCountLicenseModerate
waivedCountLicenseSevere
waivedCountLicenseCritical
waivedCountQualityLow
waivedCountQualityModerate
waivedCountQualitySevere
waivedCountQualityCritical
waivedCountOtherLow
waivedCountOtherModerate
waivedCountOtherSevere
waivedCountOtherCritical

openCountAtTimePeriodEndSecurityLow
openCountAtTimePeriodEndSecurityModerate
openCountAtTimePeriodEndSecuritySevere
openCountAtTimePeriodEndSecurityCritical
openCountAtTimePeriodEndLicenseLow
openCountAtTimePeriodEndLicenseModerate
openCountAtTimePeriodEndLicenseSevere
openCountAtTimePeriodEndLicenseCritical
openCountAtTimePeriodEndQualityLow
openCountAtTimePeriodEndQualityModerate
openCountAtTimePeriodEndQualitySevere
openCountAtTimePeriodEndQualityCritical
openCountAtTimePeriodEndOtherLow
openCountAtTimePeriodEndOtherModerate
openCountAtTimePeriodEndOtherSevere
openCountAtTimePeriodEndOtherCritical