API Reference

Reference of all available HTTP endpoints provided by Policy Reporter.

Core APIs

Healthz API

MethodAPIDescriptionCodes
GET/healthzReturns if the App is healthy and required CRDs are installed200, 503

Example

curl -X GET "http://localhost:8080/healthz"
  • Response 200
{}
  • Response 503
{ "error": "No PolicyReport CRDs found" }

Readiness API

MethodAPIDescriptionCodes
GET/readyReturns if the App is up and running200

Example

curl -X GET "http://localhost:8080/ready"
  • Response 200
{}

V1 General APIs

Targets API

MethodAPIDescriptionCodes
GET/v1/targetsList of configured targets200, 500

Example

curl -X GET "http://localhost:8080/v1/targets"
  • Response 200
[   {      "name":"UI",      "minimumPriority":"warning",      "sources":[         "Kube Bench",         "Kyverno"      ],      "skipExistingOnStartup":true   },   {      "name":"S3",      "minimumPriority":"warning",      "skipExistingOnStartup":true   }]
  • Response 500
{ "message": "Error Message" }

Policy Report API

MethodAPIDescriptionCodes
GET/v1/policy-reportsList metadata of all available PolicyReport resources200, 500

Query Filter Parameters

FilterTypeDescriptionExample
sourcesstring[]Filter by a list of sourceskyverno
labelsstring[]Filter by a list of label-value pairsenv:prod

Example

curl -X GET "http://localhost:8080/v1/policy-reports?source=kyverno&labels=env:prod"
  • Response 200
{   "items": [      {         "id": "10176812858289583969",         "name": "cpol-disallow-capabilities-strict",         "namespace": "kube-system",         "source": "kyverno",         "labels": {            "app.kubernetes.io/managed-by": "kyverno",            "cpol.kyverno.io/disallow-capabilities-strict": "12458",            "env": "prod"         },         "pass": 13,         "skip": 0,         "warn": 0,         "error": 0,         "fail": 9      }   ],   "count": 1}
  • Response 500
{ "message": "Error Message" }

Cluster Policy Report API

MethodAPIDescriptionCodes
GET/v1/cluster-policy-reportsList metadata of all available PolicyReport resources200, 500

Query Filter Parameters

FilterTypeDescriptionExample
sourcesstring[]Filter by a list of sourceskyverno
labelsstring[]Filter by a list of label-value pairsenv:prod

Example

curl -X GET "http://localhost:8080/v1/cluster-policy-reports?source=kyverno&labels=env:prod"
  • Response 200
{   "items": [      {         "id": "10176812858289583969",         "name": "cpol-disallow-capabilities-strict",         "source": "kyverno",         "labels": {            "app.kubernetes.io/managed-by": "kyverno",            "cpol.kyverno.io/disallow-capabilities-strict": "12458",            "env": "prod"         },         "pass": 13,         "skip": 0,         "warn": 0,         "error": 0,         "fail": 9      }   ],   "count": 1}
  • Response 500
{ "message": "Error Message" }

Namespaces API

MethodAPIDescriptionCodes
GET/v1/namespacesList of all Namespaces with PolicyReportResults200, 500

Query Filter Parameters

FilterTypeDescription
sourcesstring[]Filter by a list of sources
categoriesstring[]Filter by a list of categories
policiesstring[]Filter by a list of policies

Example

curl -X GET "http://localhost:8080/v1/namespaces?source=kyverno&sorce=falco"
  • Response 200
[  "policy-reporter",  "blog",  "test"]
  • Response 500
{ "message": "Error Message" }

Rule Status Count API

MethodAPIDescriptionCodes
GET/v1/rule-status-countList of counts per result
of the selected policy and rule		200, 500

Query Filter Parameters

FilterTypeDescriptionRequired
rulestringSelect the Rule for the requested countsrequired
policystringSelect the Policy of selected Rulerequired

Example

curl -X GET "http://localhost:8080/v1/rule-status-count?policy=require-non-root-groups&rule=autogen-check-fsGroup"
  • Response 200
[   {      "status":"pass",      "count":25   },   {      "status":"fail",      "count":0   },   {      "status":"warn",      "count":0   },   {      "status":"error",      "count":0   },   {      "status":"skip",      "count":0   }]
  • Response 500
{ "message": "Error Message" }

V1 PolicyReport APIs

Categories API

MethodAPIDescriptionCodes
GET/v1/namespaced-resources/categoriesList of all defined PolicyReport and ClusterPolicyReport Categories200, 500

Query Filter Parameters

FilterTypeDescription
sourcesstring[]Filter by a list of sources
namespacesstring[]Filter by a list of namespaces

Example

curl -X GET "http://localhost:8080/v1/namespaced-resources/categories?source=kyverno"
  • Response 200
[  "Pod Security Standards (Default)",  "Pod Security Standards (Restricted)"]
  • Response 500
{ "message": "Error Message" }

Policies API

MethodAPIDescriptionCodes
GET/v1/namespaced-resources/policiesList of all Policies
with namespace scoped results		200, 500

Query Filter Parameters

FilterTypeDescription
sourcesstring[]Filter by a list of sources
categoriesstring[]Filter by a list of categories
namespacesstring[]Filter by a list of namespaces

Example

curl -X GET "http://localhost:8080/v1/namespaced-resources/policies?source=kyverno"
  • Response 200
[   "deny-privilege-escalation",   "disallow-add-capabilities",   "disallow-host-namespaces",   "disallow-host-path",   "disallow-host-ports",   "disallow-privileged-containers",   "disallow-selinux",   "require-default-proc-mount",   "require-non-root-groups",   "require-run-as-non-root",   "restrict-apparmor-profiles",   "restrict-seccomp",   "restrict-sysctls",   "restrict-volume-types"]
  • Response 500
{ "message": "Error Message" }

Kinds API

MethodAPIDescriptionCodes
GET/v1/namespaced-resources/kindsList of all Kinds
with namespace scoped results		200, 500

Query Filter Parameters

FilterTypeDescription
sourcesstring[]Filter by a list of sources
namespacesstring[]Filter by a list of namespaces

Example

curl -X GET "http://localhost:8080/v1/namespaced-resources/kinds?source=kyverno"
  • Response 200
[   "CronJob",   "Deployment",   "Pod",   "StatefulSet"]
  • Response 500
{ "message": "Error Message" }

Resources API

MethodAPIDescriptionCodes
GET/v1/namespaced-resources/resourcesList of all Resources
with namespaced scoped results		200, 500

Query Filter Parameters

FilterTypeDescription
sourcesstring[]Filter by a list of sources
categoriesstring[]Filter by a list of categories
policiesstring[]Filter by a list of policies
namespacesstring[]Filter by a list of namespaces
kindsstring[]Filter by a list of kinds

Example

curl -X GET "http://localhost:8080/v1/namespaced-resources/resources?source=kyverno"
  • Response 200
[   {      "kind": "Pod",      "name": "nginx"   }]
  • Response 500
{ "message": "Error Message" }

Sources API

MethodAPIDescriptionCodes
GET/v1/namespaced-resources/sourcesList of all Sources
with namespace scoped results		200, 500

Example

curl -X GET "http://localhost:8080/v1/namespaced-resources/sources"
  • Response 200
[   "Kyverno",   "Kube Bench"]
  • Response 500
{ "message": "Error Message" }

Status Counts API

MethodAPIDescriptionCodes
GET/v1/namespaced-resources/status-countsCount of result status
per status and namespace		200, 500

Query Filter Parameters

FilterTypeDescriptionEnum
sourcesstring[]Filter by a list of sources
namespacesstring[]Filter by a list of namespaces
kindsstring[]Filter by a list of kinds
resourcesstring[]Filter by a list of resources
categoriesstring[]Filter by a list of categories
policiesstring[]Filter by a list of policies
statusstring[]Filter by a list of statusfail, pass, warn, error, skip
severitiesstring[]Filter by a list of severitieslow, medium, high

Example

curl -X GET "http://localhost:8080/v1/namespaced-resources/status-counts?source=kyverno&status=pass&status=fail"
  • Response 200
[   {      "status":"pass",      "items":[         {            "namespace":"argo-cd",            "count":206         },         {            "namespace":"blog",            "count":34         },         {            "namespace":"policy-reporter",            "count":105         },         {            "namespace":"test",            "count":34         }      ]   },   {      "status":"fail",      "items":[         {            "namespace":"argo-cd",            "count":4         },         {            "namespace":"blog",            "count":1         },         {            "namespace":"test",            "count":1         }      ]   }]
  • Response 500
{ "message": "Error Message" }

Results API

MethodAPIDescriptionCodes
GET/v1/namespaced-resources/resultsList of namespace scoped results200, 500

Query Filter Parameters

FilterTypeDescriptionEnum
sourcesstring[]Filter by a list of sources
namespacesstring[]Filter by a list of namespaces
kindsstring[]Filter by a list of kinds
resourcesstring[]Filter by a list of resources
categoriesstring[]Filter by a list of categories
policiesstring[]Filter by a list of policies
statusstring[]Filter by a list of statusfail, pass, warn, error, skip
severitiesstring[]Filter by a list of severitieslow, medium, high
searchstringFilter by search string
labelsstring[]Filter by polr label-value pairs

Optional Query Pagination Parameters

PaginationTypeDescriptionEnum
pageintRequested List Page
offsetintResults per Page
directionstringOrder of the resultsasc, desc

Example

curl -X GET "http://localhost:8080/v1/namespaced-resources/results?source=kyverno&status=fail&namespaces=test&label"
  • Response 200
{   "items": [      {         "id":"e8b7f35799c2d3cf9a50b492a8566e66dad465d9",         "namespace":"test",         "kind":"Pod",         "name":"nginx",         "category":"Pod Security Standards (Restricted)",         "message":"validation error: Running as root is not allowed. The fields spec.securityContext.runAsNonRoot, spec.containers[*].securityContext.runAsNonRoot, and spec.initContainers[*].securityContext.runAsNonRoot must be `true`. Rule check-containers[0] failed at path /spec/securityContext/runAsNonRoot/. Rule check-containers[1] failed at path /spec/containers/0/securityContext/.",         "policy":"require-run-as-non-root",         "rule":"check-containers",         "status":"fail"      }   ],   "count": 10}
  • Response 500
{ "message": "Error Message" }

V1 ClusterPolicyReport APIs

Categories API

MethodAPIDescriptionCodes
GET/v1/cluster-resources/categoriesList of all defined PolicyReport and ClusterPolicyReport Categories200, 500

Query Filter Parameters

FilterTypeDescription
sourcesstring[]Filter by a list of sources

Example

curl -X GET "http://localhost:8080/v1/cluster-resources/categories?source=kyverno"
  • Response 200
[  "Pod Security Standards (Default)",  "Pod Security Standards (Restricted)"]
  • Response 500
{ "message": "Error Message" }

Policies API

MethodAPIDescriptionCodes
GET/v1/cluster-resources/policiesList of all Policies
with cluster scoped results		200, 500

Query Filter Parameters

FilterTypeDescription
sourcesstring[]Filter by a list of sources
categoriesstring[]Filter by a list of categories

Example

curl -X GET "http://localhost:8080/v1/cluster-resources/policies?source=kyverno"
  • Response 200
[   "require-ns-labels"]
  • Response 500
{ "message": "Error Message" }

Kinds API

MethodAPIDescriptionCodes
GET/v1/cluster-resources/kindsList of all Kinds
with cluster scoped results		200, 500

Query Filter Parameters

FilterTypeDescription
sourcesstring[]Filter by a list of sources
namespacesstring[]Filter by a list of namespaces

Example

curl -X GET "http://localhost:8080/v1/cluster-resources/kinds?source=kyverno"
  • Response 200
[   "Namespace"]
  • Response 500
{ "message": "Error Message" }

Resources API

MethodAPIDescriptionCodes
GET/v1/cluster-resources/resourcesList of all Resources
with cluster scoped results		200, 500

Query Filter Parameters

FilterTypeDescription
sourcesstring[]Filter by a list of sources
categoriesstring[]Filter by a list of categories
policiesstring[]Filter by a list of policies
kindsstring[]Filter by a list of kinds

Example

curl -X GET "http://localhost:8080/v1/cluster-resources/resources?source=kyverno"
  • Response 200
[   {      "kind": "Namespace",      "name": "test"   }]
  • Response 500
{ "message": "Error Message" }

Sources API

MethodAPIDescriptionCodes
GET/v1/cluster-resources/sourcesList of all Sources
with cluster scoped results		200, 500

Example

curl -X GET "http://localhost:8080/v1/cluster-resources/sources"
  • Response 200
[   "Kyverno",   "Kube Bench"]
  • Response 500
{ "message": "Error Message" }

Status Counts API

MethodAPIDescriptionCodes
GET/v1/cluster-resources/status-countsCount of result status
per status and namespace		200, 500

Query Filter Parameters

FilterTypeDescriptionEnum
sourcesstring[]Filter by a list of sources
kindsstring[]Filter by a list of kinds
categoriesstring[]Filter by a list of categories
policiesstring[]Filter by a list of policies
statusstring[]Filter by a list of statusfail, pass, warn, error, skip
severitiesstring[]Filter by a list of severitieslow, medium, high

Example

curl -X GET "http://localhost:8080/v1/cluster-resources/status-counts?source=kyverno&status=pass&status=fail"
  • Response 200
[   {      "status":"pass",      "count":0   },   {      "status":"fail",      "count":26   }]
  • Response 500
{ "message": "Error Message" }

Results API

MethodAPIDescriptionCodes
GET/v1/cluster-resources/resultsList of cluster scoped results200, 500

Query Filter Parameters

FilterTypeDescriptionEnum
sourcesstring[]Filter by a list of sources
kindsstring[]Filter by a list of kinds
categoriesstring[]Filter by a list of categories
policiesstring[]Filter by a list of policies
statusstring[]Filter by a list of statusfail, pass, warn, error, skip
severitiesstring[]Filter by a list of severitieslow, medium, high
searchstringFilter by search string
labelsstring[]Filter by cpolr label-value pairs

Optional Query Pagination Parameters

PaginationTypeDescriptionEnum
pageintRequested List Page
offsetintResults per Page
directionstringOrder of the resultsasc, desc

Example

curl -X GET "http://localhost:8080/v1/cluster-resources/results?source=kyverno&status=fail&labels=app:test"
  • Response 200
{   "items": [      {         "id":"ca7c83998f8633b4e0da1de36e2996202e14e7a4",         "kind":"Namespace",         "name":"blog",         "category":"Convention",         "message":"validation error: The label `thisshouldntexist` is required. Rule check-for-labels-on-namespace failed at path /metadata/labels/thisshouldntexist/",         "policy":"require-ns-labels",         "rule":"check-for-labels-on-namespace",         "status":"fail"      }   ],   "count": 10}
  • Response 500
{ "message": "Error Message" }

Metrics

MethodAPIDescriptionCodes
GET/metricsPrometheus Metrics API200

cluster_policy_report_summary

Gauge: Summary count of each status per CluserPolicyReport, only available in detailed metrics mode

LabelDescription
nameName of the ClusterPolicyReport
statusStatus of the Summary count

cluster_policy_report_result

Gauge: One Entry represent one Result in a ClusterPolicyReport. Deleted Results will also be removed from the Metrics

LabelDescription
categoryCategory of the Result
kindKind of the result resource
nameName of the result resource
policyPolicy of the result
reportName of the ClusterPolicyReport where this result was found
ruleRule of the result
severitySeverity of the result
sourceSource of the result
statusStatus of the Result

policy_report_summary

Gauge: Summary count of each status per PolicyReport, only available in detailed metrics mode

LabelDescription
nameName of the PolicyReport
statusStatus of the Summary count
namespaceNamespace of the PolicyReport

policy_report_result

Gauge: One Entry represent one Result in a PolicyReport. Deleted Results will also be removed from the Metrics

LabelDescription
categoryCategory of the Result
kindKind of the result resource
nameName of the result resource
namespaceNamespace of the result resource
policyPolicy of the result
reportName of the ClusterPolicyReport where this result was found
ruleRule of the result
severitySeverity of the result
sourceSource of the result
statusStatus of the Result

Example

curl -X GET "http://localhost:8080/metrics"
  • Response 200
# HELP cluster_policy_report_result List of all ClusterPolicyReport Results
# TYPE cluster_policy_report_result gauge
cluster_policy_report_result{category="",kind="Namespace",name="argo-cd",policy="require-ns-labels",report="clusterpolicyreport",rule="check-for-labels-on-namespace",severity="",status="fail"} 1

# HELP cluster_policy_report_summary Summary of all ClusterPolicyReports
# TYPE cluster_policy_report_summary gauge
cluster_policy_report_summary{name="clusterpolicyreport",status="Error"} 0
cluster_policy_report_summary{name="clusterpolicyreport",status="Fail"} 26
cluster_policy_report_summary{name="clusterpolicyreport",status="Pass"} 0
cluster_policy_report_summary{name="clusterpolicyreport",status="Skip"} 0
cluster_policy_report_summary{name="clusterpolicyreport",status="Warn"} 0

# HELP policy_report_result List of all PolicyReport Results
# TYPE policy_report_result gauge
policy_report_result{category="Pod Security Standards (Default)",kind="Pod",name="nginx",namespace="test",policy="disallow-add-capabilities",report="polr-ns-test",rule="capabilities",severity="medium",status="pass"} 1

# HELP policy_report_summary Summary of all PolicyReports
# TYPE policy_report_summary gauge
policy_report_summary{name="polr-ns-test",namespace="test",status="Error"} 0
policy_report_summary{name="polr-ns-test",namespace="test",status="Fail"} 1
policy_report_summary{name="polr-ns-test",namespace="test",status="Pass"} 34
policy_report_summary{name="polr-ns-test",namespace="test",status="Skip"} 0
policy_report_summary{name="polr-ns-test",namespace="test",status="Warn"} 0
Table of Contents