Commit be7b30bb authored by Cameron Swords's avatar Cameron Swords

Improve documentation for engineers on how to make changes to the schema

parent c4105330
# Security report schemas changelog
## v3.0.1
- Explicitly support `additionalProperties` (!34)
## v3.0.0
- Add `scan.scanner.vendor` field to all schemas to capture the vendor/maintainer of the scanner (!33)
......
......@@ -44,8 +44,49 @@ Adding the new field to the normal `properties` field in the extension schema, o
When adding a new field, please add an appropriate check in the `tests/test-*.sh` file to verify that the merge contains the field you expect.
### Limitations
Please do not remove fields, rename fields, or change the type of fields without knowing what you're doing. These are breaking changes, and will require a major breaking release.
### Building for extensibility
Keep in mind that as the schemas grow fields will need to be altered to add more content. While the future cannot be predicted, the schemas can be made easy to change with some simple design choices.
For example, the `vendor` property in the following snippet cannot be extended, because it is of type `string`:
```json
"vendor": { "type": "string" }
```
This can be improved by making `vendor` an `object`.
```json
"vendor": {
"type": "object",
"required": ["name"],
"properties": {
"name": { "type": "string" }
}
}
```
Similarly, each link in the following example cannot be extended:
```json
"links": {
"type": "array"
"items": { "type": "string" }
}
```
This can be improved by making each item in the array an object.
```json
"links": {
"type": "array",
"items": {
"type": "object",
"required": ["url"],
"properties": {
"url": { "type": "string" }
}
}
}
```
### Pre-commit expectations
......@@ -73,10 +114,39 @@ This does the following:
- Adds release notes containing CHANGELOG description, and links to download the schemas.
Please coordinate and communicate with others when triggering a release.
Releases of the schema do not need to correspond to GitLab releases, in fact, there is no limit as to how often releases can be made.
## Versioning schemas
This repository follows the SchemaVer standard for versioning json schemas. Please read more about it [here](https://github.com/snowplow/iglu/wiki/SchemaVer).
This repository follows the [SchemaVer](https://github.com/snowplow/iglu/wiki/SchemaVer) standard to version JSON schemas.
### Classifying changes
For the following situations, you MUST increment the `MODEL.REVISION.ADDITION` version as suggested. You SHOULD refer back to
SchemaVer if your use-case is not listed.
- If you add a new optional field, you MUST use an `ADDITION` change.
- If you change an existing field to be required, or add a new required field, you MUST use a `MODEL` change. This applies even if the new required field belongs to an optional object.
- If you remove a field, you MUST use a `REVISION` change.
The use of a `MODEL` change for new required fields will result in many new `MODEL` releases. This is normal when
using SchemaVer, and does not prohibit products that depend on the Secure Report Format from being explicit regarding versions
they support.
### Additional Properties
Secure schemas allow for additional properties to be present in JSON files. This means that the schemas are only concerned with
fields in a Secure Report that are defined by the schema.
The presence of any additional fields will not cause validation to fail.
This is useful for products that produce Secure Reports:
- Experimental fields can be added to a Secure Report, without affecting how the report is used.
- It allows the product to be ahead of the Secure Report Format, when the product team is confident new fields will be merged into the schemas.
Any additional properties added to a Secure Report are considered experimental and may not be supported. For this reason,
adding optional fields to the Secure Report Format is considered an `ADDITION`, not a `REVISION` change.
## Testing
......
......@@ -3,12 +3,13 @@
"title": "Report format for GitLab Container Scanning",
"description": "This schema provides the the report format for Container Scanning (https://docs.gitlab.com/ee/user/application_security/container_scanning).",
"self": {
"version": "3.0.0"
"version": "3.0.1"
},
"required": [
"version",
"vulnerabilities"
],
"additionalProperties": true,
"properties": {
"scan": {
"type": "object",
......
......@@ -3,12 +3,13 @@
"title": "Report format for GitLab DAST",
"description": "This schema provides the the report format for Dynamic Application Security Testing (https://docs.gitlab.com/ee/user/application_security/dast).",
"self": {
"version": "3.0.0"
"version": "3.0.1"
},
"required": [
"version",
"vulnerabilities"
],
"additionalProperties": true,
"properties": {
"scan": {
"type": "object",
......
......@@ -3,13 +3,14 @@
"title": "Report format for GitLab Dependency Scanning",
"description": "This schema provides the the report format for Dependency Scanning analyzers (https://docs.gitlab.com/ee/user/application_security/dependency_scanning).",
"self": {
"version": "3.0.0"
"version": "3.0.1"
},
"required": [
"dependency_files",
"version",
"vulnerabilities"
],
"additionalProperties": true,
"properties": {
"scan": {
"type": "object",
......
......@@ -3,12 +3,13 @@
"title": "Report format for GitLab SAST",
"description": "This schema provides the report format for Static Application Security Testing analyzers (https://docs.gitlab.com/ee/user/application_security/sast).",
"self": {
"version": "3.0.0"
"version": "3.0.1"
},
"required": [
"version",
"vulnerabilities"
],
"additionalProperties": true,
"properties": {
"scan": {
"type": "object",
......
......@@ -3,12 +3,13 @@
"title": "Report format for GitLab Secret Detection",
"description": "This schema provides the the report format for the Secret Detection analyzer (https://docs.gitlab.com/ee/user/application_security/secret_detection)",
"self": {
"version": "3.0.0"
"version": "3.0.1"
},
"required": [
"version",
"vulnerabilities"
],
"additionalProperties": true,
"properties": {
"scan": {
"type": "object",
......
{
"$schema": "http://json-schema.org/draft-07/schema#",
"self": {
"version": "3.0.0"
"version": "3.0.1"
},
"title": "Common report format for GitLab security reports",
"description": "This schema provides the common report format for security reports generated by various GitLab security scanners (i.e. SAST, DAST, dependency scanning, container scanning).",
"additionalProperties": true,
"properties": {
"scan": {
"type": "object",
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment