Add scan object to the Security Reports JSON format

Problem to solve

Currently the Security reports contain vulnerabilities, but don't provide context on how these vulnerabilities were found. More specifically, they don't give any information on the security scanner and their exact settings, and can't communicate partial errors or warnings to the users.

Intended users

• Delaney (Development Team Lead)
• Sasha (Software Developer)
• Sam (Security Analyst)

Further details

Proposal

Extend the security reports and introduce a scan object that describes the security scanner and its settings, as well as the scan itself (duration, status, possible errors).

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "http://secure.gitlab.com/common-report-format.json",
  "type": "object",
  "title": "Common Report Format",
  "description": "JSON schema used by GitLab Secure Products",
  "required": ["scan"],
  "properties": {
    "scan": {
      "type": "object",
      "required": [
        "end_time",
        "messages",
        "scanner",
        "start_time",
        "status",
        "type"
      ],
      "properties": {
        "end_time": {
          "type": "string",
          "description": "ISO8601 UTC value with format yyyy-mm-ddThh:mm:ss, representing when the scan finished",
          "examples": ["2020-01-28T03:26:02"]
        },
        "messages": {
          "type":  "array",
          "items": { "$ref": "#/definitions/message" }
        },
        "scanner": {
          "type": "object",
          "description": "Object defining the scanner used to perform the scan",
          "required": [
            "id",
            "name",
            "version"
          ],
          "properties": {
            "id": {
              "type": "string",
              "description": "Unique id that identifies the scanner",
              "examples": ["sastscanner5000"]
            },
            "name": {
              "type": "string",
              "description": "A human readable value that identifies the scanner, not required to be unique",
              "examples": ["SAST Scanner 5000"]
            },
            "url": {
              "type": "string",
              "description": "A link to more information about the scanner",
              "examples": ["https://scanner.url/documentation"]
            },
            "version": {
              "type": "string",
              "description": "The version of the scanner",
              "examples": ["1.0.2"]
            }
          }
        },
        "start_time": {
          "type": "string",
          "description": "ISO8601 UTC value with format yyyy-mm-ddThh:mm:ss, representing when the scan started",
          "examples": ["2020-02-14T16:01:59"]
        },
        "status": {
          "type": "string",
          "description": "Result of the scan",
          "enum": ["success", "failure"],
          "examples": ["success"]
        },
        "type": {
          "type": "string",
          "description": "Type of the scan",
          "enum": [
            "container_scanning",
            "dependency_scanning",
            "dynamic_application_security_testing",
            "static_application_security_testing"
          ],
          "examples": ["static_application_security_testing"]
        }
      }
    }
  },
  "definitions": {
    "message": {
      "type": "object",
      "description": "Communication intended for the initiator of a scan",
      "required": ["level", "value"],
      "properties": {
        "level": {
          "type": "string",
          "description": "Describes the severity of the communication",
          "enum": ["info", "warn", "error"],
          "examples": ["info"]
        },
        "value": {
          "type": "string",
          "description": "The message to communicate",
          "examples": "Permission denied, scanning aborted"
        }
      }
    }
  }
}

Previous example of Scan object

{
  "scan": {
    "id": "123456",
    "end_time": "ISO8601 yyyy-mm-ddThh:mm:ss in UTC",
    "start_time": "ISO8601 yyyy-mm-ddThh:mm:ss in UTC",
    "status": "success",
    "status_message": "used as a human friendly message to explain whether the scan succeeded or failed. Could include a code or other information for the user to understand the status. Should not be used for details. Should be limited to XX number of characters. ",
    "scanner": {
      "id": "sastscanner5000",
      "name": "SAST Scanner 5000",
      "uri": "https://scanner.url/documentation",
      "version": "1.0.2"
    },
    "configuration": {
      "name": "value"
    },
    "targets": [
      {
        "type": "url",
        "value": "initiating url of the scan e.g. http://www.my-target.com/fun-times"
      },
      {
        "type": "repo",
        "value": "http://www.gitlab.com/myrepo"
      },
      {
        "type": "image",
        "value": "registry.gitlab.com/gitlab-org/security-products/tests/js-npm/node-modules:latest"
      },
      {
        "type": "file",
        "value": "file.rb"
      }
    ]
  }
}

Permissions and Security

Documentation

Testing

What does success look like, and how can we measure that?

Users reading a Security report know the context in which vulnerabilities were found.

Also, GitLab can leverage the scan field to show this context in the UI, and to report warnings and errors.

What is the type of buyer?

Links / references