openshift · aweiteka · Apr 19, 2017 · Apr 20, 2017 · Apr 20, 2017
diff --git a/security/container_content.adoc b/security/container_content.adoc
@@ -57,6 +57,242 @@ analysis tools that identify open source libraries in order to provide metadata
 on those libraries such as known vulnerabilities. This is covered in more detail
 in xref:{sourcedir}security/build_process.adoc#security-build[Build Process].
 
+[[integrate-external-scanners]]
+== Integrating External Scanning Tools with OpenShift
+
+OpenShift makes use of link:https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/[object annotations]
+to extend functionality. External tools, such as vulnerability scanners, may
+annotate image objects with metadata to summarize results and control pod
+execution. This section describes the recognized format of this annotation so it
+may be reliably used in consoles to display useful data to users.
+
+[[image-metadata]]
+=== Image Metadata
+
+There are different types of image quality data, including package
+vulnerabilities and open source software (OSS) license compliance. Additionally,
+there may be more than one provider of this metadata. To that end, the following
+annotation format has been reserved:
+
+====
+----
+quality.images.openshift.io/<qualityType>.<providerId>: {}
+----
+====
+
+.Annotation key format
+[option="header"]
+|===
+|Component |Description |Acceptable values
+
+|qualityType
+|metadata type
+|vulnerability, license, operations
+
+|providerId
+|provider ID string
+|redhatcloudforms, redhatcatalog, redhatinsights, blackduck, jfrog
+|===
+
+==== Example Annotation Keys
+
+====
+----
+quality.images.openshift.io/vulnerability.blackduck: {}
+quality.images.openshift.io/vulnerability.jfrog: {}
+quality.images.openshift.io/license.blackduck: {}
+quality.images.openshift.io/vulnerability.redhatcloudforms: {}
+----
+====
+
+The value of the image quality annotation is structured data that must adhere to
+the following format:
+
+.Annotation value format
+[option="header"]
+|===
+|Field |Required? |Description |Type
+
+|name
+|yes
+|provider display name
+|string
+
+|timestamp
+|yes
+|scan timestamp
+|int
+
+|description
+|no
+|short description
+|string
+
+|reference
+|no
+|URL for detailed information
+|string
+
+|compliant
+|no
+|compliance pass/fail
+|boolean
+
+|summary
+|no
+|summary of vulnerabilities found
+|list (see table below)
+|===
+
+The *summary* field must adhere to the following format:
+
+.Summary field value format
+[option="header"]
+|===
+|Field |Description |Type
+
+|label
+|display label for component, e.g. critical, important, moderate, low or freshness.
+|string
+
+|score
+|score for this component, e.g. count of vulnerabilities found
+|int
+
+|severityIndex
+|component score index allowing for ordering and assigning graphical
+representation. The value is a range where 0=low or none.
+|int
+|===
+
+==== Example Annotation Values
+
+In this example, a Red Hat CloudForms annotation for an image with vulnerability
+summary data and a compliance boolean.
+
+.Red Hat CloudForms Annotation
+[source,json]
+----
+{
+  “name”: “CloudForms”,
+  “description”: “vulnerability score”,
+  “timestamp”: 2147483647,
+  “reference”: null,
+  “compliant”: true,
+  “summary”: [
+    { “label”: “critical”, “score”: 4, “severityIndex”: 3 },
+    { “label”: “important”, “score”: 12, “severityIndex”: 2 },
+    { “label”: “moderate”, “score”: 8, “severityIndex”: 1 },
+    { “label”: “low”, “score”: 26, “severityIndex”: 0 }
+  ]
+}
+----
+
+In this example, a Red Hat Container Catalog annotation for an image with
+vulnerability summary data with an external URL for additional details.
+
+.Red Hat Container Catalog Annotation
+[source,json]
+----
+{
+  “name”: “Red Hat Container Catalog”,
+  “description”: “Container freshness score”,
+  “timestamp”: 2147483647,
+  “reference”: “https://access.redhat.com/errata/RHBA-2016:1566”,
+  “compliant”: null,
+  “summary”: [
+    { “label”: “Freshness”, “score”: 4, “severityIndex”: 4 }
+  ]
+}
+----
+
+[[annotating-image-objects]]
+=== Annotating Image Objects
+
+While xref:../architecture/core_concepts/builds_and_image_streams.html#image-streams[imagestream objects]
+are what an end-user of OpenShift operates against, xref:../rest_api/openshift_v1.html#v1-image[image objects]
+are annotated with security metadata. Image objects are cluster-scoped, pointing
+to a single image that may be referenced by many imagestreams and tags.
+
+==== Example annotate CLI command
+
+Replace *IMAGE* with an image name, e.g. *sha256:fec8a395afe3e804b3db5cb277869142d2b5c561ebb517585566e160ff321988*.
+
+====
+----
+$ oc annotate image IMAGE \
+    quality.images.openshift.io/vulnerability.redhatcatalog='{
+    "name": "Red Hat Container Catalog",
+    “description”: “Container freshness score”,
+    “timestamp”: 2147483647,
+    “compliant”: null,
+    "reference": “https://access.redhat.com/errata/RHBA-2016:1566”,
+    "summary": “[
+      { “label”: “Freshness”, “score”: 4, “severityIndex”: 4 } ]" }'
+----
+====
+
+[[controlling-pod-execution]]
+=== Controlling Pod Execution
+
+To programmatically control if an image may be run, the
+*images.openshift.io/deny-execution* image policy may be used. See
+xref:../admin_guide/image_policy.adoc[image policy] for more information.
+
+==== Example annotation
+
+[source,yaml]
+----
+annotations:
+  images.openshift.io/deny-execution: true
+----
+
+[[integration-reference]]
+=== Integration Reference
+
+In most cases, external tools such as vulnerability scanners will develop a
+script or plugin that watches for image updates, performs scanning
+and annotate the associated image object with the results. Typically this
+automation calls the OpenShift REST API to write the annotation.
+See xref:../rest_api/index.adoc[REST API documentation] for general information
+on the REST API and xref:../rest_api/openshift_v1.adoc#partially-update-the-specified-image[**PATCH** call to update images].
+
+==== Example REST API Call
+
+This example call using cURL will overwrite the value of the annotation. Be sure
+to replace the values for *TOKEN*, *OPENSHIFT_SERVER*, image ID and
+*IMAGE_ANNOTATION*.
+
+.Patch API call
+----
+$ curl -X PATCH \
+  -H "Authorization: Bearer TOKEN" \
+  -H "Content-Type: application/merge-patch+json" \
+  https://OPENSHIFT_SERVER:8443/oapi/v1/images/sha256:fec8a395afe3e804b3db5cb277869142d2b5c561ebb517585566e160ff321988 \
+  --data '{ IMAGE_ANNOTATION }'
+----
+
+Below is example *PATCH* payload data.
+
+.Patch call data
+----
+{
+"metadata": {
+  "annotations": {
+    "quality.images.openshift.io/vulnerability.redhatcatalog":
+       "{ 'name': 'Red Hat Container Catalog', 'description': 'Container freshness score', 'timestamp': 2147483647, 'compliant': null, 'reference': 'https://access.redhat.com/errata/RHBA-2016:1566', 'summary': [{'label': 'Freshness', 'score': 4, 'severityIndex': 4}] }"
+    }
+  }
+}
+----
+
+[NOTE]
+====
+Due to the complexity of this API call and challenges with escaping characters,
+an API developer tool such as link:https://www.getpostman.com/[Postman] may
+assist in creating API calls.
+====
+
 [discrete]
 [[security-content-further-reading-2]]
 ==== Further Reading

diff --git a/using_images/db_images/mariadb.adoc b/using_images/db_images/mariadb.adoc
@@ -91,7 +91,7 @@ If you want to set only the mandatory environment variables, and not store the
 database in a host directory, run:
 
 ----
-ifdef::openshift-enterprise[]
+ifdef::openshift-enterprise,openshift-online[]
 $ docker run -d --name mariadb_database -e MYSQL_USER=user -e MYSQL_PASSWORD=pass -e MYSQL_DATABASE=db -p 3306:3306 rhscl/mariadb-100-rhel7
 endif::[]
 ifdef::openshift-origin[]