From 48cbaca8a0c19daba8a06f9088bf7fb71335d1cd Mon Sep 17 00:00:00 2001 From: Michael D Brown Date: Fri, 2 May 2025 08:44:33 -0400 Subject: [PATCH] Update apis (#526) * Update apis Closes #436 Updates APIs to 1.2-rc1 ahead of unscored round 2 * Update values.yaml * Bump competition/crs API to v1.2 * Breaking changes in competition api config * Check for SARIFs in CI (#527) * Check for SARIFs in CI * Remove trailing bracket --------- Co-authored-by: Henrik Brodin <90325907+hbrodin@users.noreply.github.com> --- .github/workflows/integration.yml | 26 + competition-server/compose.yaml | 2 +- competition-server/scantron.yaml | 9 + .../competition-api/templates/configmap.yaml | 9 + deployment/k8s/values.yaml | 2 +- orchestrator/docs/README.md | 41 + orchestrator/docs/TypesArchitecture.md | 2 +- orchestrator/docs/TypesAssessment.md | 4 +- orchestrator/docs/TypesSubmissionStatus.md | 10 +- orchestrator/docs/api/CHANGELOG.md | 8 +- orchestrator/docs/api/README.md | 114 +- .../docs/api/competition-swagger-v1.2.0.json | 1122 ++++++ .../docs/api/competition-swagger-v1.2.0.yaml | 860 +++++ .../docs/api/competition-swagger.json | 96 +- .../docs/api/competition-swagger.yaml | 74 +- orchestrator/docs/api/crs-swagger-v1.2.0.json | 404 ++ orchestrator/docs/api/crs-swagger-v1.2.0.yaml | 361 ++ orchestrator/docs/api/crs-swagger.json | 10 +- orchestrator/docs/api/crs-swagger.yaml | 18 +- .../docs/api/sarif-schema-v1.2.0.json | 3315 +++++++++++++++++ orchestrator/docs/api/sarif-schema.json | 8 +- .../hosted_competitor_test_server.md | 68 + .../tailscale_management_tools.md | 44 + orchestrator/docs/telemetry/README.md | 2 + .../telemetry/telemetry_best_practices.md | 29 + orchestrator/pyproject.toml | 2 +- .../orchestrator/.openapi-generator/VERSION | 2 +- .../models/types_architecture.py | 2 +- .../models/types_assessment.py | 4 +- .../models/types_submission_status.py | 10 +- .../orchestrator/scheduler/submissions.py | 81 +- .../task_server/models/__init__.py | 4 +- .../orchestrator/task_server/models/types.py | 4 +- .../orchestrator/task_server/server.py | 2 +- orchestrator/test/test_submissions.py | 79 +- 35 files changed, 6676 insertions(+), 152 deletions(-) create mode 100644 orchestrator/docs/README.md create mode 100644 orchestrator/docs/api/competition-swagger-v1.2.0.json create mode 100644 orchestrator/docs/api/competition-swagger-v1.2.0.yaml create mode 100644 orchestrator/docs/api/crs-swagger-v1.2.0.json create mode 100644 orchestrator/docs/api/crs-swagger-v1.2.0.yaml create mode 100644 orchestrator/docs/api/sarif-schema-v1.2.0.json create mode 100644 orchestrator/docs/tailscale-hosted-competitor-test-server/hosted_competitor_test_server.md create mode 100644 orchestrator/docs/tailscale-hosted-competitor-test-server/tailscale_management_tools.md create mode 100644 orchestrator/docs/telemetry/telemetry_best_practices.md diff --git a/.github/workflows/integration.yml b/.github/workflows/integration.yml index c53cd450..b5882872 100644 --- a/.github/workflows/integration.yml +++ b/.github/workflows/integration.yml @@ -34,12 +34,17 @@ on: description: "Timeout for bundle submission in minutes" required: false default: "" + sarif_timeout: + description: "Timeout for SARIF submission in minutes" + required: false + default: "" env: FUZZER_BUILD_TIMEOUT: ${{ inputs.build_timeout || 20 }} VULN_TIMEOUT: ${{ inputs.vuln_timeout || 25 }} PATCH_TIMEOUT: ${{ inputs.patch_timeout || 15 }} BUNDLE_TIMEOUT: ${{ inputs.bundle_timeout || 5 }} + SARIF_TIMEOUT: ${{ inputs.sarif_timeout || 5 }} FUZZ_TOOLING_CONTAINER_ORG: ${{ inputs.fuzz_tooling_container_org || 'aixcc-afc' }} permissions: @@ -175,6 +180,27 @@ jobs: while ! kubectl logs -n $BUTTERCUP_NAMESPACE -l app=scheduler | grep "SUBMIT_BUNDLE -> SUBMIT_MATCHING_SARIF"; do sleep 10 done + - name: Send a SARIF broadcast + timeout-minutes: ${{ fromJSON(env.SARIF_TIMEOUT) }} + run: | + TASK_ID=$(kubectl logs -n $BUTTERCUP_NAMESPACE -l app=scheduler | grep "SUBMIT_BUNDLE -> SUBMIT_MATCHING_SARIF" | grep -o "\[[^]]*\]" | grep -o "[^[]*$" | cut -d: -f2 | tr -d ']') + echo "Task ID: $TASK_ID" + kubectl port-forward -n $BUTTERCUP_NAMESPACE service/buttercup-competition-api 31323:1323 & + sleep 5 + ./orchestrator/scripts/send_sarif.sh $TASK_ID + sleep 5 + - name: Wait for SARIF to be submitted as correct + timeout-minutes: ${{ fromJSON(env.SARIF_TIMEOUT) }} + run: | + while ! kubectl logs -n $BUTTERCUP_NAMESPACE -l app=scheduler | grep "SUBMIT_MATCHING_SARIF -> SUBMIT_BUNDLE_PATCH"; do + sleep 10 + done + - name: Wait for Bundle to be patched to include the SARIF + timeout-minutes: ${{ fromJSON(env.SARIF_TIMEOUT) }} + run: | + while ! kubectl logs -n $BUTTERCUP_NAMESPACE -l app=scheduler | grep "SUBMIT_BUNDLE_PATCH -> STOP"; do + sleep 10 + done # TODO: re-enable seed-gen once it's fixed # - name: Wait for seed-gen to find PoV # timeout-minutes: 10 # low timeout because already waiting for prior steps diff --git a/competition-server/compose.yaml b/competition-server/compose.yaml index 985ec48c..a551727f 100644 --- a/competition-server/compose.yaml +++ b/competition-server/compose.yaml @@ -35,7 +35,7 @@ services: # - shared-tmp:/tmp scantron: - image: ghcr.io/aixcc-finals/example-crs-architecture/competition-test-api:v1.1-rc7 + image: ghcr.io/aixcc-finals/example-crs-architecture/competition-test-api:v1.2-rc1 platform: linux/amd64 privileged: true volumes: diff --git a/competition-server/scantron.yaml b/competition-server/scantron.yaml index dfe92a92..8554a60f 100644 --- a/competition-server/scantron.yaml +++ b/competition-server/scantron.yaml @@ -39,3 +39,12 @@ api_host_and_port: "scantron:31323" # # github Personal Access token. This is used by the server to download the # # appropriate fuzz tooling if not using public repositories # pat: ghp_XXXXXXXXXXXXXXXXXXXXX +generate: + enabled: true + delta: + repo_url: "https://github.com/aixcc-finals/integration-test.git" + base_ref: "5ac0917575e20464b5aa86434dff2a7626b558b4" + head_ref: "challenges/integration-test-delta-01" + fuzz_tooling_url: "https://github.com/aixcc-finals/oss-fuzz-aixcc.git" + fuzz_tooling_ref: "v1.1.0" + fuzz_tooling_project_name: "integration-test" \ No newline at end of file diff --git a/deployment/k8s/charts/competition-api/templates/configmap.yaml b/deployment/k8s/charts/competition-api/templates/configmap.yaml index d3aba880..79dcd57a 100644 --- a/deployment/k8s/charts/competition-api/templates/configmap.yaml +++ b/deployment/k8s/charts/competition-api/templates/configmap.yaml @@ -37,3 +37,12 @@ data: listen_address: "[::]:1323" api_host_and_port: "{{ .Release.Name }}-competition-api.{{ .Release.Namespace }}.svc.cluster.local:1323" {{- end }} + generate: + enabled: true + delta: + repo_url: "https://github.com/aixcc-finals/integration-test.git" + base_ref: "5ac0917575e20464b5aa86434dff2a7626b558b4" + head_ref: "challenges/integration-test-delta-01" + fuzz_tooling_url: "https://github.com/aixcc-finals/oss-fuzz-aixcc.git" + fuzz_tooling_ref: "v1.1.0" + fuzz_tooling_project_name: "integration-test" diff --git a/deployment/k8s/values.yaml b/deployment/k8s/values.yaml index 57d62811..5afc74fa 100644 --- a/deployment/k8s/values.yaml +++ b/deployment/k8s/values.yaml @@ -30,7 +30,7 @@ global: pullSecrets: ["ghcr-auth"] competitionApiImage: repository: ghcr.io/aixcc-finals/example-crs-architecture/competition-test-api - tag: v1.1-rc7 + tag: v1.2-rc1 pullPolicy: Always pullSecrets: ["ghcr-auth"] diff --git a/orchestrator/docs/README.md b/orchestrator/docs/README.md new file mode 100644 index 00000000..cc5eee59 --- /dev/null +++ b/orchestrator/docs/README.md @@ -0,0 +1,41 @@ +# AIxCC Final Documentation + +Welcome to the documentation page for the AIxCC Final Competition. + +## Table of Contents + +- [Changelog](api/CHANGELOG.md#changelog) + - [1.2.0](api/CHANGELOG.md#120) + - [v1.1.1](api/CHANGELOG.md#v111) + - [v1.1](api/CHANGELOG.md#v11) + - [v1.0](api/CHANGELOG.md#v10) + - [v0.4](api/CHANGELOG.md#v04) + - [v0.3](api/CHANGELOG.md#v03) +- [API](api/README.md#api) + - [Competition API Interaction](api/README.md#competition-api-interaction) + - [Submitting a vulnerability](api/README.md#submitting-a-vulnerability) + - [Submitting a SARIF assessment](api/README.md#submitting-a-sarif-assessment) + - [Submitting a patch](api/README.md#submitting-a-patch) + - [Submitting a bundle](api/README.md#submitting-a-bundle) + - [Request Integration Test Task](api/README.md#request-integration-test-task) + - [CRS API Task Statuses](api/README.md#crs-api-task-statuses) + - [Generating a Client or Server](api/README.md#generating-a-client-or-server) + - [OpenAPI Generator](api/README.md#openapi-generator) + - [Viewing the UI](api/README.md#viewing-the-ui) +- [CRS Telemetry Specification v1.0](telemetry/README.md#crs-telemetry-specification-v10) + - [GenAI (LLM requests and responses)](telemetry/README.md#genai-llm-requests-and-responses) + - [CRS Actions](telemetry/README.md#crs-actions) + - [Resource Attributes](telemetry/README.md#resource-attributes) + - [Mandatory Span Attributes](telemetry/README.md#mandatory-span-attributes) + - [Optional Attributes](telemetry/README.md#optional-attributes) + - [Specialized Attributes for LLM Requests](telemetry/README.md#specialized-attributes-for-llm-requests) + - [Specialized Attributes for Fuzzing](telemetry/README.md#specialized-attributes-for-fuzzing) + - [Example Python Implementation](telemetry/README.md#example-python-implementation) + - [Alternative Python Implementation](telemetry/README.md#alternative-python-implementation) + - [Example CRS Webservice](telemetry/README.md#example-crs-webservice) + - [Other Usage Examples](telemetry/README.md#other-usage-examples) +- [General telemetry guidance](telemetry/telemetry_best_practices.md#general-telemetry-guidance) + - [Improving the structure of OTEL data](telemetry/telemetry_best_practices.md#improving-the-structure-of-otel-data) + - [Verifying telemetry](telemetry/telemetry_best_practices.md#verifying-telemetry) +- [Tailnet-accessible hosted Competitor Test Server](tailscale-hosted-competitor-test-server/hosted_competitor_test_server.md#tailnet-accessible-hosted-competitor-test-server) +- [Tailscale Management Tools](tailscale-hosted-competitor-test-server/tailscale_management_tools.md#tailscale-management-tools) diff --git a/orchestrator/docs/TypesArchitecture.md b/orchestrator/docs/TypesArchitecture.md index aa634e63..c8887e75 100644 --- a/orchestrator/docs/TypesArchitecture.md +++ b/orchestrator/docs/TypesArchitecture.md @@ -3,7 +3,7 @@ ## Enum -* `X86_64` (value: `'x86_64'`) +* `ArchitectureX8664` (value: `'x86_64'`) [[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md) diff --git a/orchestrator/docs/TypesAssessment.md b/orchestrator/docs/TypesAssessment.md index 967f3386..dcec8bd6 100644 --- a/orchestrator/docs/TypesAssessment.md +++ b/orchestrator/docs/TypesAssessment.md @@ -3,9 +3,9 @@ ## Enum -* `CORRECT` (value: `'correct'`) +* `AssessmentCorrect` (value: `'correct'`) -* `INCORRECT` (value: `'incorrect'`) +* `AssessmentIncorrect` (value: `'incorrect'`) [[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md) diff --git a/orchestrator/docs/TypesSubmissionStatus.md b/orchestrator/docs/TypesSubmissionStatus.md index 13a9401c..8074f61a 100644 --- a/orchestrator/docs/TypesSubmissionStatus.md +++ b/orchestrator/docs/TypesSubmissionStatus.md @@ -3,15 +3,15 @@ ## Enum -* `ACCEPTED` (value: `'accepted'`) +* `SubmissionStatusAccepted` (value: `'accepted'`) -* `PASSED` (value: `'passed'`) +* `SubmissionStatusPassed` (value: `'passed'`) -* `FAILED` (value: `'failed'`) +* `SubmissionStatusFailed` (value: `'failed'`) -* `DEADLINE_EXCEEDED` (value: `'deadline_exceeded'`) +* `SubmissionStatusDeadlineExceeded` (value: `'deadline_exceeded'`) -* `ERRORED` (value: `'errored'`) +* `SubmissionStatusErrored` (value: `'errored'`) [[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md) diff --git a/orchestrator/docs/api/CHANGELOG.md b/orchestrator/docs/api/CHANGELOG.md index 1833643a..fe339e57 100644 --- a/orchestrator/docs/api/CHANGELOG.md +++ b/orchestrator/docs/api/CHANGELOG.md @@ -1,5 +1,10 @@ # Changelog +## 1.2.0 + +- revert to the default SARIF schema removing the required property on `ruleId` +- add endpoint for requesting an integration test challenge + ## v1.1.1 - correct typo in swagger docs tags for freeform submission @@ -40,8 +45,7 @@ For more information, see: - Added optional `sarif_id` on patch submissions - Added large max sizes to most string fields on the Competition API - Added note that max sizes for base64 fields are before encoding -- Added metadata fields to Task and SARIF broadcasts containing a string to string map that should be attached - to outputs like log messages and OpenTelemetry trace attributes for traceability +- Added metadata fields to Task and SARIF broadcasts containing a string to string map that should be attached to outputs like log messages and OpenTelemetry trace attributes for traceability - Added `focus` and `project_name` to Task broadcasts. - Project name is the OSS Fuzz project name for the task. - Focus is the name of the directory in the `repo` tarball that vulns, patches, and SARIF broadcasts should be submitted against. diff --git a/orchestrator/docs/api/README.md b/orchestrator/docs/api/README.md index df3e9635..6fad9b7f 100644 --- a/orchestrator/docs/api/README.md +++ b/orchestrator/docs/api/README.md @@ -1,47 +1,12 @@ # API -See the [API Changelog](./docs/api/CHANGELOG.md) for information on recent API changes. +See the [API Changelog](./CHANGELOG.md) for information on recent API changes. -- Competitors will consume the API described by `competition-swagger-v1.1.1.yaml` -- Competitors will provide the API described by `crs-swagger-v1.1.yaml` +- Competitors will consume the API described by `competition-swagger.yaml` +- Competitors will provide the API described by `crs-swagger.yaml` NOTE: The JSON and YAML documents contain the same information and are generated from the same source. -These files describe the CRS API and the Example Competition API. [Swagger](https://swagger.io/blog/api-strategy/difference-between-swagger-and-openapi/) is an ecosystem built around the [OpenAPI](https://www.openapis.org/what-is-openapi) -specification with which it is possible to render a UI documenting the API, to generate client code to interact with the API, and to generate -server code to be the API. In essence, the OpenAPI specification is a standard way of documenting HTTP APIs. This allows tools built to consume the description -to be portable across APIs. - -The different components can be used as needed for different applications. The Example Competition API specification -is generated using inline code comments and served under the `/swagger/` path. A web framework specific third-party dependency that included the -swagger-ui was used to provide the endpoints. - -## Viewing the UI - -The provided Example Competition API will serve the swagger UI at `/swagger/index.html`. The spec is served at `/swagger/doc.json` -Competitors may find it useful to do something similar for their CRS. - -Most webserver frameworks will have a package that can be used to help serve the UI. If this is not possible or you do not wish to use a third-party package, -the source can be downloaded from [https://github.com/swagger-api/swagger-ui/releases](https://github.com/swagger-api/swagger-ui/releases). -After unpacking the archive using tar or ZIP, the precompiled source can be found in the `dist` directory. - -If you do not wish to integrate the UI directly into the CRS system it is still possible to use for development. - -- Using the same method described above, download and unpack the release. -- Place any number of swagger specs inside the `swagger-ui/dist` folder. -- Start a basic webserver from the `swagger-ui/dist` folder. For example the built-in Python 3 webserver: - -```bash -# PWD: swagger-ui/dist -python -m http.server -``` - -- Change the path to the swagger file at the top of your page to the desired file. For example, `/competition-swagger-v0.1.json` if you placed - a swagger spec called `competition-swagger-v0.1.json` at `swagger-ui/dist/competition-swagger-v0.1.json`. -- This will only allow viewing the documentation. Experimenting with the API endpoints requires a running API server serving the spec file. - If the spec is served from the API server and it supports CORS, it is possible to specify the full URL to the spec in the box. - This will allow you to experiment with the API using the `Try it Out` button. - ## Competition API Interaction During the competition, the Competition API sends tasks and SARIF broadcasts to CRSs and receives responses of several types (vulnerability, patch, or SARIF assessment). The Example Competition API checks interfaces @@ -106,6 +71,29 @@ CRS->>API: Create Bundle "accepted" CRS->>API: Modify Bundle ``` +### Request Integration Test Task + +After deploying your CRS, you now have the ability to task your CRS with a simple “[integration test](https://github.com/aixcc-finals/integration-test/tree/challenges/integration-test-delta-01)” challenge (delta scan) to +make sure your CRS and Telemetry are working as expected prior to the opening of the Round. + +This endpoint is available from now until 5 minutes prior to the opening of a Round. It is accessible from the internet and from inside the tailnet. `duration_secs` is an optional parameter, and defaults to 4 hours. +Provide your Competition API credentials to kick off the task. This will send a task to the Round's expected CRS hostname (e.g. `team-moniker-exhibition2` for exhibition2) on the tailnet. + +```mermaid +sequenceDiagram + accTitle: Smoke Test Workflow + + User->>API: /v1/request/delta + API->>CRS: Hardcoded integration-test task + CRS->>API: POV/Patch/Bundle/Sarif Submission +``` + +Here is an example curl you may use to trigger the integration testing task. + +```bash +curl -u 11111111-1111-1111-1111-111111111111:pY8rLk7FvQ2hZm9GwUx3Ej5BnTcV4So0 -X 'POST' 'https://api.aixcc.tech/v1/request/delta/' -H 'Content-Type: application/json' -d '{"duration_secs": 3600 }' +``` + ## CRS API Task Statuses The CRS API has a status endpoint which provides a summary of tasks by status, among other things. The statuses which tasks go through are documented in the state diagram below. @@ -127,12 +115,13 @@ stateDiagram-v2 ## Generating a Client or Server -It is possible to generate client or server code from the swagger documents. The documents are a best effort to provide a strongly typed schema but are not perfect. -Use the generators at your own discretion as they are not maintained by AIxCC and may not produce working code. +It is possible to generate client or server code from the swagger documents. The documents are a best effort to provide a strongly typed schema but are not perfect. Use the generators at your own discretion as they are +not maintained by AIxCC and may not produce working code. ### OpenAPI Generator -OpenAPI generator is a fork and actively maintained continuation of the swagger-codegen project. The source code can be found here: [https://github.com/openapitools/openapi-generator](https://github.com/openapitools/openapi-generator). +OpenAPI generator is a fork and actively maintained continuation of the swagger-codegen project. The source code can be found here: +[https://github.com/openapitools/openapi-generator](https://github.com/openapitools/openapi-generator). To run the generator using docker or podman: @@ -143,18 +132,49 @@ docker run --rm -v $PWD:/local openapitools/openapi-generator-cli generate \ -o /local/out ``` -- `-v $PWD:/local` mounts the current working directory into the `/local` directory in the container. - A different host path could be provided for `$PWD`. All paths used in the following steps would be relative to the new path instead of `$PWD`. +- `-v $PWD:/local` mounts the current working directory into the `/local` directory in the container. A different host path could be provided for `$PWD`. All paths used in the following steps would be relative to the new + path instead of `$PWD`. - All arguments after `openapitools/openapi-generator-cli` are passed to the generator CLI inside the container -- `-i /local/competition-swagger-v0.1.json` is the path relative to the current working directory of the swagger file. On the host, `competition-swagger-v-0.1.json` is located in `$PWD`. - If you want to change the file or path it must be a descendant of `$PWD`. +- `-i /local/competition-swagger-v0.1.json` is the path relative to the current working directory of the swagger file. On the host, `competition-swagger-v-0.1.json` is located in `$PWD`. If you want to change the file or + path it must be a descendant of `$PWD`. - `-g lang` is used to specify the generator to run. If you pass an invalid value it will list all of the options. - `-o /local/out` is the path relative to the current working directory to output the generated code. -- A language specific config file can be optionally provided using `-c /local/path_to_config` [Project Docs](https://github.com/OpenAPITools/openapi-generator/blob/b218e238f4f6cac8c919a78b296d3062bdfec0be/docs/customization.md#customizing-the-generator). - The available config options can be found using the `config-help -g lang` subcommand instead of `generate`. +- A language specific config file can be optionally provided using `-c /local/path_to_config` + [Project Docs](https://github.com/OpenAPITools/openapi-generator/blob/b218e238f4f6cac8c919a78b296d3062bdfec0be/docs/customization.md#customizing-the-generator). The available config options can be found using the + `config-help -g lang` subcommand instead of `generate`. To see all available options for the generate command: ```bash docker run --rm -v $PWD:/local openapitools/openapi-generator-cli help generate ``` + +### Viewing the UI + +The swagger documents describe the CRS API and the Example Competition API. [Swagger](https://swagger.io/blog/api-strategy/difference-between-swagger-and-openapi/) is an ecosystem built around the +[OpenAPI](https://www.openapis.org/what-is-openapi) specification with which it is possible to render a UI documenting the API, to generate client code to interact with the API, and to generate server code to be the API. +In essence, the OpenAPI specification is a standard way of documenting HTTP APIs. This allows tools built to consume the description to be portable across APIs. + +The different components can be used as needed for different applications. The Example Competition API specification is generated using inline code comments and served under the `/swagger/` path. A web framework specific +third-party dependency that included the swagger-ui was used to provide the endpoints. + +The provided Example Competition API will serve the swagger UI at `/swagger/index.html`. The spec is served at `/swagger/doc.json` Competitors may find it useful to do something similar for their CRS. + +Most webserver frameworks will have a package that can be used to help serve the UI. If this is not possible or you do not wish to use a third-party package, the source can be downloaded from +[https://github.com/swagger-api/swagger-ui/releases](https://github.com/swagger-api/swagger-ui/releases). After unpacking the archive using tar or ZIP, the precompiled source can be found in the `dist` directory. + +If you do not wish to integrate the UI directly into the CRS system it is still possible to use for development. + +- Using the same method described above, download and unpack the release. +- Place any number of swagger specs inside the `swagger-ui/dist` folder. +- Start a basic webserver from the `swagger-ui/dist` folder. For example the built-in Python 3 webserver: + +```bash +# PWD: swagger-ui/dist +python -m http.server +``` + +- Change the path to the swagger file at the top of your page to the desired file. For example, `/competition-swagger-v0.1.json` if you placed a swagger spec called `competition-swagger-v0.1.json` at + `swagger-ui/dist/competition-swagger-v0.1.json`. +- This will only allow viewing the documentation. Experimenting with the API endpoints requires a running API server serving the spec file. If the spec is served from the API server and it supports CORS, it is possible + to specify the full URL to the spec in the box. This will allow you to experiment with the API using the `Try it Out` button. diff --git a/orchestrator/docs/api/competition-swagger-v1.2.0.json b/orchestrator/docs/api/competition-swagger-v1.2.0.json new file mode 100644 index 00000000..2a4ea4c8 --- /dev/null +++ b/orchestrator/docs/api/competition-swagger-v1.2.0.json @@ -0,0 +1,1122 @@ +{ + "swagger": "2.0", + "info": { + "title": "Example Competition API", + "contact": {}, + "version": "1.2.0" + }, + "paths": { + "/v1/ping/": { + "get": { + "security": [ + { + "BasicAuth": [] + } + ], + "description": "Test authentication creds and network connectivity", + "consumes": ["application/json"], + "tags": ["ping"], + "summary": "Test authentication creds and network connectivity", + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/types.PingResponse" + } + } + } + } + }, + "/v1/request/delta/": { + "post": { + "security": [ + { + "BasicAuth": [] + } + ], + "description": "Send a delta task to the source of this request", + "consumes": ["application/json"], + "produces": ["application/json"], + "tags": ["request"], + "summary": "Send a delta task to the source of this request", + "parameters": [ + { + "description": "Submission Body", + "name": "payload", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/types.RequestSubmission" + } + } + ], + "responses": { + "200": { + "description": "No Content", + "schema": { + "type": "string" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/types.Error" + } + }, + "401": { + "description": "Unauthorized", + "schema": { + "$ref": "#/definitions/types.Error" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/types.Error" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/types.Error" + } + } + } + } + }, + "/v1/task/{task_id}/broadcast-sarif-assessment/{broadcast_sarif_id}/": { + "post": { + "security": [ + { + "BasicAuth": [] + } + ], + "description": "Submit a SARIF assessment", + "consumes": ["application/json"], + "produces": ["application/json"], + "tags": ["broadcast-sarif-assessment"], + "summary": "Submit a SARIF Assessment", + "parameters": [ + { + "type": "string", + "format": "uuid", + "description": "Task ID", + "name": "task_id", + "in": "path", + "required": true + }, + { + "type": "string", + "format": "uuid", + "description": "Broadcast SARIF ID", + "name": "broadcast_sarif_id", + "in": "path", + "required": true + }, + { + "description": "Submission body", + "name": "payload", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/types.SarifAssessmentSubmission" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/types.SarifAssessmentResponse" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/types.Error" + } + }, + "401": { + "description": "Unauthorized", + "schema": { + "$ref": "#/definitions/types.Error" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/types.Error" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/types.Error" + } + } + } + } + }, + "/v1/task/{task_id}/bundle/": { + "post": { + "security": [ + { + "BasicAuth": [] + } + ], + "description": "submits a bundle", + "consumes": ["application/json"], + "produces": ["application/json"], + "tags": ["bundle"], + "summary": "Submit Bundle", + "parameters": [ + { + "type": "string", + "format": "uuid", + "description": "Task ID", + "name": "task_id", + "in": "path", + "required": true + }, + { + "description": "Submission Body", + "name": "payload", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/types.BundleSubmission" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/types.BundleSubmissionResponse" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/types.Error" + } + }, + "401": { + "description": "Unauthorized", + "schema": { + "$ref": "#/definitions/types.Error" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/types.Error" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/types.Error" + } + } + } + } + }, + "/v1/task/{task_id}/bundle/{bundle_id}/": { + "get": { + "security": [ + { + "BasicAuth": [] + } + ], + "description": "get a bundle", + "consumes": ["application/json"], + "produces": ["application/json"], + "tags": ["bundle"], + "summary": "Get Bundle", + "parameters": [ + { + "type": "string", + "format": "uuid", + "description": "Task ID", + "name": "task_id", + "in": "path", + "required": true + }, + { + "type": "string", + "format": "uuid", + "description": "Bundle ID", + "name": "bundle_id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/types.BundleSubmissionResponseVerbose" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/types.Error" + } + }, + "401": { + "description": "Unauthorized", + "schema": { + "$ref": "#/definitions/types.Error" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/types.Error" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/types.Error" + } + } + } + }, + "delete": { + "security": [ + { + "BasicAuth": [] + } + ], + "description": "delete a bundle", + "consumes": ["application/json"], + "produces": ["application/json"], + "tags": ["bundle"], + "summary": "Delete Bundle", + "parameters": [ + { + "type": "string", + "format": "uuid", + "description": "Task ID", + "name": "task_id", + "in": "path", + "required": true + }, + { + "type": "string", + "format": "uuid", + "description": "Bundle ID", + "name": "bundle_id", + "in": "path", + "required": true + } + ], + "responses": { + "204": { + "description": "No Content", + "schema": { + "type": "string" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/types.Error" + } + }, + "401": { + "description": "Unauthorized", + "schema": { + "$ref": "#/definitions/types.Error" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/types.Error" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/types.Error" + } + } + } + }, + "patch": { + "security": [ + { + "BasicAuth": [] + } + ], + "description": "updates a bundle", + "consumes": ["application/json"], + "produces": ["application/json"], + "tags": ["bundle"], + "summary": "Update Bundle", + "parameters": [ + { + "type": "string", + "format": "uuid", + "description": "Task ID", + "name": "task_id", + "in": "path", + "required": true + }, + { + "type": "string", + "format": "uuid", + "description": "Bundle ID", + "name": "bundle_id", + "in": "path", + "required": true + }, + { + "description": "Submission Body", + "name": "payload", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/types.BundleSubmission" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/types.BundleSubmissionResponseVerbose" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/types.Error" + } + }, + "401": { + "description": "Unauthorized", + "schema": { + "$ref": "#/definitions/types.Error" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/types.Error" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/types.Error" + } + } + } + } + }, + "/v1/task/{task_id}/freeform/": { + "post": { + "security": [ + { + "BasicAuth": [] + } + ], + "description": "submits a freeform pov", + "consumes": ["application/json"], + "produces": ["application/json"], + "tags": ["freeform"], + "summary": "Submit Freeform", + "parameters": [ + { + "type": "string", + "format": "uuid", + "description": "Task ID", + "name": "task_id", + "in": "path", + "required": true + }, + { + "description": "Submission Body", + "name": "payload", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/types.FreeformSubmission" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/types.FreeformResponse" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/types.Error" + } + }, + "401": { + "description": "Unauthorized", + "schema": { + "$ref": "#/definitions/types.Error" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/types.Error" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/types.Error" + } + } + } + } + }, + "/v1/task/{task_id}/patch/": { + "post": { + "security": [ + { + "BasicAuth": [] + } + ], + "description": "submit a patch for testing", + "consumes": ["application/json"], + "produces": ["application/json"], + "tags": ["patch"], + "summary": "Submit Patch", + "parameters": [ + { + "type": "string", + "format": "uuid", + "description": "Task ID", + "name": "task_id", + "in": "path", + "required": true + }, + { + "description": "Payload", + "name": "payload", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/types.PatchSubmission" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/types.PatchSubmissionResponse" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/types.Error" + } + }, + "401": { + "description": "Unauthorized", + "schema": { + "$ref": "#/definitions/types.Error" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/types.Error" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/types.Error" + } + } + } + } + }, + "/v1/task/{task_id}/patch/{patch_id}/": { + "get": { + "security": [ + { + "BasicAuth": [] + } + ], + "description": "yield the status of patch testing", + "consumes": ["application/json"], + "produces": ["application/json"], + "tags": ["patch"], + "summary": "Patch Status", + "parameters": [ + { + "type": "string", + "format": "uuid", + "description": "Task ID", + "name": "task_id", + "in": "path", + "required": true + }, + { + "type": "string", + "format": "uuid", + "description": "Patch ID", + "name": "patch_id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/types.PatchSubmissionResponse" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/types.Error" + } + }, + "401": { + "description": "Unauthorized", + "schema": { + "$ref": "#/definitions/types.Error" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/types.Error" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/types.Error" + } + } + } + } + }, + "/v1/task/{task_id}/pov/": { + "post": { + "security": [ + { + "BasicAuth": [] + } + ], + "description": "submit a vulnerability for testing", + "consumes": ["application/json"], + "produces": ["application/json"], + "tags": ["pov"], + "summary": "Submit Vulnerability", + "parameters": [ + { + "type": "string", + "format": "uuid", + "description": "Task ID", + "name": "task_id", + "in": "path", + "required": true + }, + { + "description": "Submission body", + "name": "payload", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/types.POVSubmission" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/types.POVSubmissionResponse" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/types.Error" + } + }, + "401": { + "description": "Unauthorized", + "schema": { + "$ref": "#/definitions/types.Error" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/types.Error" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/types.Error" + } + } + } + } + }, + "/v1/task/{task_id}/pov/{pov_id}/": { + "get": { + "security": [ + { + "BasicAuth": [] + } + ], + "description": "yield the status of vuln testing", + "consumes": ["application/json"], + "produces": ["application/json"], + "tags": ["pov"], + "summary": "Vulnerability Status", + "parameters": [ + { + "type": "string", + "format": "uuid", + "description": "Task ID", + "name": "task_id", + "in": "path", + "required": true + }, + { + "type": "string", + "format": "uuid", + "description": "POV ID", + "name": "pov_id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/types.POVSubmissionResponse" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/types.Error" + } + }, + "401": { + "description": "Unauthorized", + "schema": { + "$ref": "#/definitions/types.Error" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/types.Error" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/types.Error" + } + } + } + } + }, + "/v1/task/{task_id}/submitted-sarif/": { + "post": { + "security": [ + { + "BasicAuth": [] + } + ], + "description": "Submit a CRS generated SARIF", + "consumes": ["application/json"], + "produces": ["application/json"], + "tags": ["submitted-sarif"], + "summary": "Submit a CRS generated SARIF", + "parameters": [ + { + "type": "string", + "format": "uuid", + "description": "Task ID", + "name": "task_id", + "in": "path", + "required": true + }, + { + "description": "Submission body", + "name": "payload", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/types.SARIFSubmission" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/types.SARIFSubmissionResponse" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/types.Error" + } + }, + "401": { + "description": "Unauthorized", + "schema": { + "$ref": "#/definitions/types.Error" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/types.Error" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/types.Error" + } + } + } + } + } + }, + "definitions": { + "types.Architecture": { + "type": "string", + "enum": ["x86_64"], + "x-enum-varnames": ["ArchitectureX8664"] + }, + "types.Assessment": { + "type": "string", + "enum": ["correct", "incorrect"], + "x-enum-varnames": ["AssessmentCorrect", "AssessmentIncorrect"] + }, + "types.BundleSubmission": { + "type": "object", + "properties": { + "broadcast_sarif_id": { + "type": "string", + "format": "uuid" + }, + "description": { + "description": "optional plaintext description of the components of the bundle, such as would be found in a pull request description or bug report", + "type": "string" + }, + "freeform_id": { + "type": "string", + "format": "uuid" + }, + "patch_id": { + "type": "string", + "format": "uuid" + }, + "pov_id": { + "type": "string", + "format": "uuid" + }, + "submitted_sarif_id": { + "type": "string", + "format": "uuid" + } + } + }, + "types.BundleSubmissionResponse": { + "type": "object", + "required": ["bundle_id", "status"], + "properties": { + "bundle_id": { + "type": "string", + "format": "uuid" + }, + "status": { + "description": "Schema-compliant submissions will only ever receive the statuses accepted or deadline_exceeded", + "allOf": [ + { + "$ref": "#/definitions/types.SubmissionStatus" + } + ] + } + } + }, + "types.BundleSubmissionResponseVerbose": { + "type": "object", + "required": ["bundle_id", "status"], + "properties": { + "broadcast_sarif_id": { + "type": "string", + "format": "uuid" + }, + "bundle_id": { + "type": "string", + "format": "uuid" + }, + "description": { + "type": "string" + }, + "freeform_id": { + "type": "string", + "format": "uuid" + }, + "patch_id": { + "type": "string", + "format": "uuid" + }, + "pov_id": { + "type": "string", + "format": "uuid" + }, + "status": { + "description": "Schema-compliant submissions will only ever receive the statuses accepted or deadline_exceeded", + "allOf": [ + { + "$ref": "#/definitions/types.SubmissionStatus" + } + ] + }, + "submitted_sarif_id": { + "type": "string", + "format": "uuid" + } + } + }, + "types.Error": { + "type": "object", + "required": ["message"], + "properties": { + "fields": { + "type": "object", + "additionalProperties": { + "type": "string" + } + }, + "message": { + "type": "string" + } + } + }, + "types.FreeformResponse": { + "type": "object", + "required": ["freeform_id", "status"], + "properties": { + "freeform_id": { + "type": "string", + "format": "uuid" + }, + "status": { + "description": "Schema-compliant submissions will only ever receive the statuses accepted or deadline_exceeded", + "allOf": [ + { + "$ref": "#/definitions/types.SubmissionStatus" + } + ] + } + } + }, + "types.FreeformSubmission": { + "type": "object", + "required": ["submission"], + "properties": { + "submission": { + "description": "Base64 encoded arbitrary data\n\n2MiB max size before Base64 encoding", + "type": "string" + } + } + }, + "types.POVSubmission": { + "type": "object", + "required": [ + "architecture", + "engine", + "fuzzer_name", + "sanitizer", + "testcase" + ], + "properties": { + "architecture": { + "$ref": "#/definitions/types.Architecture" + }, + "engine": { + "description": "Fuzz Tooling Engine that exercises this vuln. Allowable engine values are specified in project.yaml.\n\n4KiB max size", + "type": "string", + "maxLength": 4096 + }, + "fuzzer_name": { + "description": "Fuzz Tooling fuzzer that exercises this vuln\n\n4KiB max size", + "type": "string", + "maxLength": 4096 + }, + "sanitizer": { + "description": "Fuzz Tooling Sanitizer that exercises this vuln\n\n4KiB max size", + "type": "string", + "maxLength": 4096 + }, + "testcase": { + "description": "Base64 encoded vuln trigger\n\n2MiB max size before Base64 encoding", + "type": "string", + "format": "base64" + } + } + }, + "types.POVSubmissionResponse": { + "type": "object", + "required": ["pov_id", "status"], + "properties": { + "pov_id": { + "type": "string", + "format": "uuid" + }, + "status": { + "$ref": "#/definitions/types.SubmissionStatus" + } + } + }, + "types.PatchSubmission": { + "type": "object", + "required": ["patch"], + "properties": { + "patch": { + "description": "Base64 encoded patch in unified diff format\n\n100KiB max size before Base64 encoding", + "type": "string", + "format": "base64" + } + } + }, + "types.PatchSubmissionResponse": { + "type": "object", + "required": ["patch_id", "status"], + "properties": { + "functionality_tests_passing": { + "description": "null indicates the tests have not been run", + "type": "boolean" + }, + "patch_id": { + "type": "string", + "format": "uuid" + }, + "status": { + "$ref": "#/definitions/types.SubmissionStatus" + } + } + }, + "types.PingResponse": { + "type": "object", + "required": ["status"], + "properties": { + "status": { + "type": "string" + } + } + }, + "types.RequestSubmission": { + "type": "object", + "properties": { + "duration_secs": { + "description": "Time in seconds until a task should expire. If not provided, defaults to 3600.", + "type": "integer" + } + } + }, + "types.SARIFSubmission": { + "type": "object", + "required": ["sarif"], + "properties": { + "sarif": { + "description": "SARIF object compliant with the provided schema", + "type": "object" + } + } + }, + "types.SARIFSubmissionResponse": { + "type": "object", + "required": ["status", "submitted_sarif_id"], + "properties": { + "status": { + "description": "Schema-compliant submissions will only ever receive the statuses accepted or deadline_exceeded", + "allOf": [ + { + "$ref": "#/definitions/types.SubmissionStatus" + } + ] + }, + "submitted_sarif_id": { + "type": "string", + "format": "uuid" + } + } + }, + "types.SarifAssessmentResponse": { + "type": "object", + "required": ["status"], + "properties": { + "status": { + "$ref": "#/definitions/types.SubmissionStatus" + } + } + }, + "types.SarifAssessmentSubmission": { + "type": "object", + "required": ["assessment", "description"], + "properties": { + "assessment": { + "$ref": "#/definitions/types.Assessment" + }, + "description": { + "description": "Plain text reasoning for the assessment\n\n128KiB max size", + "type": "string", + "maxLength": 131072 + } + } + }, + "types.SubmissionStatus": { + "type": "string", + "enum": ["accepted", "passed", "failed", "deadline_exceeded", "errored"], + "x-enum-comments": { + "SubmissionStatusAccepted": "Successfully submitted", + "SubmissionStatusDeadlineExceeded": "Task deadline exceeded. All submissions marked accepted before the deadline will be evaluated.", + "SubmissionStatusErrored": "Server side error when testing submission", + "SubmissionStatusFailed": "Submission failed testing", + "SubmissionStatusPassed": "Successfully evaluated submission" + }, + "x-enum-varnames": [ + "SubmissionStatusAccepted", + "SubmissionStatusPassed", + "SubmissionStatusFailed", + "SubmissionStatusDeadlineExceeded", + "SubmissionStatusErrored" + ] + } + }, + "securityDefinitions": { + "BasicAuth": { + "type": "basic" + } + } +} diff --git a/orchestrator/docs/api/competition-swagger-v1.2.0.yaml b/orchestrator/docs/api/competition-swagger-v1.2.0.yaml new file mode 100644 index 00000000..6c8e1c19 --- /dev/null +++ b/orchestrator/docs/api/competition-swagger-v1.2.0.yaml @@ -0,0 +1,860 @@ +definitions: + types.Architecture: + enum: + - x86_64 + type: string + x-enum-varnames: + - ArchitectureX8664 + types.Assessment: + enum: + - correct + - incorrect + type: string + x-enum-varnames: + - AssessmentCorrect + - AssessmentIncorrect + types.BundleSubmission: + properties: + broadcast_sarif_id: + format: uuid + type: string + description: + description: + optional plaintext description of the components of the bundle, + such as would be found in a pull request description or bug report + type: string + freeform_id: + format: uuid + type: string + patch_id: + format: uuid + type: string + pov_id: + format: uuid + type: string + submitted_sarif_id: + format: uuid + type: string + type: object + types.BundleSubmissionResponse: + properties: + bundle_id: + format: uuid + type: string + status: + allOf: + - $ref: "#/definitions/types.SubmissionStatus" + description: + Schema-compliant submissions will only ever receive the statuses + accepted or deadline_exceeded + required: + - bundle_id + - status + type: object + types.BundleSubmissionResponseVerbose: + properties: + broadcast_sarif_id: + format: uuid + type: string + bundle_id: + format: uuid + type: string + description: + type: string + freeform_id: + format: uuid + type: string + patch_id: + format: uuid + type: string + pov_id: + format: uuid + type: string + status: + allOf: + - $ref: "#/definitions/types.SubmissionStatus" + description: + Schema-compliant submissions will only ever receive the statuses + accepted or deadline_exceeded + submitted_sarif_id: + format: uuid + type: string + required: + - bundle_id + - status + type: object + types.Error: + properties: + fields: + additionalProperties: + type: string + type: object + message: + type: string + required: + - message + type: object + types.FreeformResponse: + properties: + freeform_id: + format: uuid + type: string + status: + allOf: + - $ref: "#/definitions/types.SubmissionStatus" + description: + Schema-compliant submissions will only ever receive the statuses + accepted or deadline_exceeded + required: + - freeform_id + - status + type: object + types.FreeformSubmission: + properties: + submission: + description: |- + Base64 encoded arbitrary data + + 2MiB max size before Base64 encoding + type: string + required: + - submission + type: object + types.POVSubmission: + properties: + architecture: + $ref: "#/definitions/types.Architecture" + engine: + description: |- + Fuzz Tooling Engine that exercises this vuln. Allowable engine values are specified in project.yaml. + + 4KiB max size + maxLength: 4096 + type: string + fuzzer_name: + description: |- + Fuzz Tooling fuzzer that exercises this vuln + + 4KiB max size + maxLength: 4096 + type: string + sanitizer: + description: |- + Fuzz Tooling Sanitizer that exercises this vuln + + 4KiB max size + maxLength: 4096 + type: string + testcase: + description: |- + Base64 encoded vuln trigger + + 2MiB max size before Base64 encoding + format: base64 + type: string + required: + - architecture + - engine + - fuzzer_name + - sanitizer + - testcase + type: object + types.POVSubmissionResponse: + properties: + pov_id: + format: uuid + type: string + status: + $ref: "#/definitions/types.SubmissionStatus" + required: + - pov_id + - status + type: object + types.PatchSubmission: + properties: + patch: + description: |- + Base64 encoded patch in unified diff format + + 100KiB max size before Base64 encoding + format: base64 + type: string + required: + - patch + type: object + types.PatchSubmissionResponse: + properties: + functionality_tests_passing: + description: null indicates the tests have not been run + type: boolean + patch_id: + format: uuid + type: string + status: + $ref: "#/definitions/types.SubmissionStatus" + required: + - patch_id + - status + type: object + types.PingResponse: + properties: + status: + type: string + required: + - status + type: object + types.RequestSubmission: + properties: + duration_secs: + description: + Time in seconds until a task should expire. If not provided, + defaults to 3600. + type: integer + type: object + types.SARIFSubmission: + properties: + sarif: + description: SARIF object compliant with the provided schema + type: object + required: + - sarif + type: object + types.SARIFSubmissionResponse: + properties: + status: + allOf: + - $ref: "#/definitions/types.SubmissionStatus" + description: + Schema-compliant submissions will only ever receive the statuses + accepted or deadline_exceeded + submitted_sarif_id: + format: uuid + type: string + required: + - status + - submitted_sarif_id + type: object + types.SarifAssessmentResponse: + properties: + status: + $ref: "#/definitions/types.SubmissionStatus" + required: + - status + type: object + types.SarifAssessmentSubmission: + properties: + assessment: + $ref: "#/definitions/types.Assessment" + description: + description: |- + Plain text reasoning for the assessment + + 128KiB max size + maxLength: 131072 + type: string + required: + - assessment + - description + type: object + types.SubmissionStatus: + enum: + - accepted + - passed + - failed + - deadline_exceeded + - errored + type: string + x-enum-comments: + SubmissionStatusAccepted: Successfully submitted + SubmissionStatusDeadlineExceeded: + Task deadline exceeded. All submissions marked + accepted before the deadline will be evaluated. + SubmissionStatusErrored: Server side error when testing submission + SubmissionStatusFailed: Submission failed testing + SubmissionStatusPassed: Successfully evaluated submission + x-enum-varnames: + - SubmissionStatusAccepted + - SubmissionStatusPassed + - SubmissionStatusFailed + - SubmissionStatusDeadlineExceeded + - SubmissionStatusErrored +info: + contact: {} + title: Example Competition API + version: 1.2.0 +paths: + /v1/ping/: + get: + consumes: + - application/json + description: Test authentication creds and network connectivity + responses: + "200": + description: OK + schema: + $ref: "#/definitions/types.PingResponse" + security: + - BasicAuth: [] + summary: Test authentication creds and network connectivity + tags: + - ping + /v1/request/delta/: + post: + consumes: + - application/json + description: Send a delta task to the source of this request + parameters: + - description: Submission Body + in: body + name: payload + required: true + schema: + $ref: "#/definitions/types.RequestSubmission" + produces: + - application/json + responses: + "200": + description: No Content + schema: + type: string + "400": + description: Bad Request + schema: + $ref: "#/definitions/types.Error" + "401": + description: Unauthorized + schema: + $ref: "#/definitions/types.Error" + "404": + description: Not Found + schema: + $ref: "#/definitions/types.Error" + "500": + description: Internal Server Error + schema: + $ref: "#/definitions/types.Error" + security: + - BasicAuth: [] + summary: Send a delta task to the source of this request + tags: + - request + /v1/task/{task_id}/broadcast-sarif-assessment/{broadcast_sarif_id}/: + post: + consumes: + - application/json + description: Submit a SARIF assessment + parameters: + - description: Task ID + format: uuid + in: path + name: task_id + required: true + type: string + - description: Broadcast SARIF ID + format: uuid + in: path + name: broadcast_sarif_id + required: true + type: string + - description: Submission body + in: body + name: payload + required: true + schema: + $ref: "#/definitions/types.SarifAssessmentSubmission" + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: "#/definitions/types.SarifAssessmentResponse" + "400": + description: Bad Request + schema: + $ref: "#/definitions/types.Error" + "401": + description: Unauthorized + schema: + $ref: "#/definitions/types.Error" + "404": + description: Not Found + schema: + $ref: "#/definitions/types.Error" + "500": + description: Internal Server Error + schema: + $ref: "#/definitions/types.Error" + security: + - BasicAuth: [] + summary: Submit a SARIF Assessment + tags: + - broadcast-sarif-assessment + /v1/task/{task_id}/bundle/: + post: + consumes: + - application/json + description: submits a bundle + parameters: + - description: Task ID + format: uuid + in: path + name: task_id + required: true + type: string + - description: Submission Body + in: body + name: payload + required: true + schema: + $ref: "#/definitions/types.BundleSubmission" + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: "#/definitions/types.BundleSubmissionResponse" + "400": + description: Bad Request + schema: + $ref: "#/definitions/types.Error" + "401": + description: Unauthorized + schema: + $ref: "#/definitions/types.Error" + "404": + description: Not Found + schema: + $ref: "#/definitions/types.Error" + "500": + description: Internal Server Error + schema: + $ref: "#/definitions/types.Error" + security: + - BasicAuth: [] + summary: Submit Bundle + tags: + - bundle + /v1/task/{task_id}/bundle/{bundle_id}/: + delete: + consumes: + - application/json + description: delete a bundle + parameters: + - description: Task ID + format: uuid + in: path + name: task_id + required: true + type: string + - description: Bundle ID + format: uuid + in: path + name: bundle_id + required: true + type: string + produces: + - application/json + responses: + "204": + description: No Content + schema: + type: string + "400": + description: Bad Request + schema: + $ref: "#/definitions/types.Error" + "401": + description: Unauthorized + schema: + $ref: "#/definitions/types.Error" + "404": + description: Not Found + schema: + $ref: "#/definitions/types.Error" + "500": + description: Internal Server Error + schema: + $ref: "#/definitions/types.Error" + security: + - BasicAuth: [] + summary: Delete Bundle + tags: + - bundle + get: + consumes: + - application/json + description: get a bundle + parameters: + - description: Task ID + format: uuid + in: path + name: task_id + required: true + type: string + - description: Bundle ID + format: uuid + in: path + name: bundle_id + required: true + type: string + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: "#/definitions/types.BundleSubmissionResponseVerbose" + "400": + description: Bad Request + schema: + $ref: "#/definitions/types.Error" + "401": + description: Unauthorized + schema: + $ref: "#/definitions/types.Error" + "404": + description: Not Found + schema: + $ref: "#/definitions/types.Error" + "500": + description: Internal Server Error + schema: + $ref: "#/definitions/types.Error" + security: + - BasicAuth: [] + summary: Get Bundle + tags: + - bundle + patch: + consumes: + - application/json + description: updates a bundle + parameters: + - description: Task ID + format: uuid + in: path + name: task_id + required: true + type: string + - description: Bundle ID + format: uuid + in: path + name: bundle_id + required: true + type: string + - description: Submission Body + in: body + name: payload + required: true + schema: + $ref: "#/definitions/types.BundleSubmission" + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: "#/definitions/types.BundleSubmissionResponseVerbose" + "400": + description: Bad Request + schema: + $ref: "#/definitions/types.Error" + "401": + description: Unauthorized + schema: + $ref: "#/definitions/types.Error" + "404": + description: Not Found + schema: + $ref: "#/definitions/types.Error" + "500": + description: Internal Server Error + schema: + $ref: "#/definitions/types.Error" + security: + - BasicAuth: [] + summary: Update Bundle + tags: + - bundle + /v1/task/{task_id}/freeform/: + post: + consumes: + - application/json + description: submits a freeform pov + parameters: + - description: Task ID + format: uuid + in: path + name: task_id + required: true + type: string + - description: Submission Body + in: body + name: payload + required: true + schema: + $ref: "#/definitions/types.FreeformSubmission" + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: "#/definitions/types.FreeformResponse" + "400": + description: Bad Request + schema: + $ref: "#/definitions/types.Error" + "401": + description: Unauthorized + schema: + $ref: "#/definitions/types.Error" + "404": + description: Not Found + schema: + $ref: "#/definitions/types.Error" + "500": + description: Internal Server Error + schema: + $ref: "#/definitions/types.Error" + security: + - BasicAuth: [] + summary: Submit Freeform + tags: + - freeform + /v1/task/{task_id}/patch/: + post: + consumes: + - application/json + description: submit a patch for testing + parameters: + - description: Task ID + format: uuid + in: path + name: task_id + required: true + type: string + - description: Payload + in: body + name: payload + required: true + schema: + $ref: "#/definitions/types.PatchSubmission" + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: "#/definitions/types.PatchSubmissionResponse" + "400": + description: Bad Request + schema: + $ref: "#/definitions/types.Error" + "401": + description: Unauthorized + schema: + $ref: "#/definitions/types.Error" + "404": + description: Not Found + schema: + $ref: "#/definitions/types.Error" + "500": + description: Internal Server Error + schema: + $ref: "#/definitions/types.Error" + security: + - BasicAuth: [] + summary: Submit Patch + tags: + - patch + /v1/task/{task_id}/patch/{patch_id}/: + get: + consumes: + - application/json + description: yield the status of patch testing + parameters: + - description: Task ID + format: uuid + in: path + name: task_id + required: true + type: string + - description: Patch ID + format: uuid + in: path + name: patch_id + required: true + type: string + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: "#/definitions/types.PatchSubmissionResponse" + "400": + description: Bad Request + schema: + $ref: "#/definitions/types.Error" + "401": + description: Unauthorized + schema: + $ref: "#/definitions/types.Error" + "404": + description: Not Found + schema: + $ref: "#/definitions/types.Error" + "500": + description: Internal Server Error + schema: + $ref: "#/definitions/types.Error" + security: + - BasicAuth: [] + summary: Patch Status + tags: + - patch + /v1/task/{task_id}/pov/: + post: + consumes: + - application/json + description: submit a vulnerability for testing + parameters: + - description: Task ID + format: uuid + in: path + name: task_id + required: true + type: string + - description: Submission body + in: body + name: payload + required: true + schema: + $ref: "#/definitions/types.POVSubmission" + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: "#/definitions/types.POVSubmissionResponse" + "400": + description: Bad Request + schema: + $ref: "#/definitions/types.Error" + "401": + description: Unauthorized + schema: + $ref: "#/definitions/types.Error" + "404": + description: Not Found + schema: + $ref: "#/definitions/types.Error" + "500": + description: Internal Server Error + schema: + $ref: "#/definitions/types.Error" + security: + - BasicAuth: [] + summary: Submit Vulnerability + tags: + - pov + /v1/task/{task_id}/pov/{pov_id}/: + get: + consumes: + - application/json + description: yield the status of vuln testing + parameters: + - description: Task ID + format: uuid + in: path + name: task_id + required: true + type: string + - description: POV ID + format: uuid + in: path + name: pov_id + required: true + type: string + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: "#/definitions/types.POVSubmissionResponse" + "400": + description: Bad Request + schema: + $ref: "#/definitions/types.Error" + "401": + description: Unauthorized + schema: + $ref: "#/definitions/types.Error" + "404": + description: Not Found + schema: + $ref: "#/definitions/types.Error" + "500": + description: Internal Server Error + schema: + $ref: "#/definitions/types.Error" + security: + - BasicAuth: [] + summary: Vulnerability Status + tags: + - pov + /v1/task/{task_id}/submitted-sarif/: + post: + consumes: + - application/json + description: Submit a CRS generated SARIF + parameters: + - description: Task ID + format: uuid + in: path + name: task_id + required: true + type: string + - description: Submission body + in: body + name: payload + required: true + schema: + $ref: "#/definitions/types.SARIFSubmission" + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: "#/definitions/types.SARIFSubmissionResponse" + "400": + description: Bad Request + schema: + $ref: "#/definitions/types.Error" + "401": + description: Unauthorized + schema: + $ref: "#/definitions/types.Error" + "404": + description: Not Found + schema: + $ref: "#/definitions/types.Error" + "500": + description: Internal Server Error + schema: + $ref: "#/definitions/types.Error" + security: + - BasicAuth: [] + summary: Submit a CRS generated SARIF + tags: + - submitted-sarif +securityDefinitions: + BasicAuth: + type: basic +swagger: "2.0" diff --git a/orchestrator/docs/api/competition-swagger.json b/orchestrator/docs/api/competition-swagger.json index c4a71a85..2a4ea4c8 100644 --- a/orchestrator/docs/api/competition-swagger.json +++ b/orchestrator/docs/api/competition-swagger.json @@ -3,7 +3,7 @@ "info": { "title": "Example Competition API", "contact": {}, - "version": "1.1.1" + "version": "1.2.0" }, "paths": { "/v1/ping/": { @@ -27,6 +27,63 @@ } } }, + "/v1/request/delta/": { + "post": { + "security": [ + { + "BasicAuth": [] + } + ], + "description": "Send a delta task to the source of this request", + "consumes": ["application/json"], + "produces": ["application/json"], + "tags": ["request"], + "summary": "Send a delta task to the source of this request", + "parameters": [ + { + "description": "Submission Body", + "name": "payload", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/types.RequestSubmission" + } + } + ], + "responses": { + "200": { + "description": "No Content", + "schema": { + "type": "string" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/types.Error" + } + }, + "401": { + "description": "Unauthorized", + "schema": { + "$ref": "#/definitions/types.Error" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/types.Error" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/types.Error" + } + } + } + } + }, "/v1/task/{task_id}/broadcast-sarif-assessment/{broadcast_sarif_id}/": { "post": { "security": [ @@ -800,7 +857,12 @@ "format": "uuid" }, "status": { - "$ref": "#/definitions/types.SubmissionStatus" + "description": "Schema-compliant submissions will only ever receive the statuses accepted or deadline_exceeded", + "allOf": [ + { + "$ref": "#/definitions/types.SubmissionStatus" + } + ] } } }, @@ -832,7 +894,12 @@ "format": "uuid" }, "status": { - "$ref": "#/definitions/types.SubmissionStatus" + "description": "Schema-compliant submissions will only ever receive the statuses accepted or deadline_exceeded", + "allOf": [ + { + "$ref": "#/definitions/types.SubmissionStatus" + } + ] }, "submitted_sarif_id": { "type": "string", @@ -864,7 +931,12 @@ "format": "uuid" }, "status": { - "$ref": "#/definitions/types.SubmissionStatus" + "description": "Schema-compliant submissions will only ever receive the statuses accepted or deadline_exceeded", + "allOf": [ + { + "$ref": "#/definitions/types.SubmissionStatus" + } + ] } } }, @@ -963,6 +1035,15 @@ } } }, + "types.RequestSubmission": { + "type": "object", + "properties": { + "duration_secs": { + "description": "Time in seconds until a task should expire. If not provided, defaults to 3600.", + "type": "integer" + } + } + }, "types.SARIFSubmission": { "type": "object", "required": ["sarif"], @@ -978,7 +1059,12 @@ "required": ["status", "submitted_sarif_id"], "properties": { "status": { - "$ref": "#/definitions/types.SubmissionStatus" + "description": "Schema-compliant submissions will only ever receive the statuses accepted or deadline_exceeded", + "allOf": [ + { + "$ref": "#/definitions/types.SubmissionStatus" + } + ] }, "submitted_sarif_id": { "type": "string", diff --git a/orchestrator/docs/api/competition-swagger.yaml b/orchestrator/docs/api/competition-swagger.yaml index facd3a74..6c8e1c19 100644 --- a/orchestrator/docs/api/competition-swagger.yaml +++ b/orchestrator/docs/api/competition-swagger.yaml @@ -42,7 +42,11 @@ definitions: format: uuid type: string status: - $ref: "#/definitions/types.SubmissionStatus" + allOf: + - $ref: "#/definitions/types.SubmissionStatus" + description: + Schema-compliant submissions will only ever receive the statuses + accepted or deadline_exceeded required: - bundle_id - status @@ -67,7 +71,11 @@ definitions: format: uuid type: string status: - $ref: "#/definitions/types.SubmissionStatus" + allOf: + - $ref: "#/definitions/types.SubmissionStatus" + description: + Schema-compliant submissions will only ever receive the statuses + accepted or deadline_exceeded submitted_sarif_id: format: uuid type: string @@ -92,7 +100,11 @@ definitions: format: uuid type: string status: - $ref: "#/definitions/types.SubmissionStatus" + allOf: + - $ref: "#/definitions/types.SubmissionStatus" + description: + Schema-compliant submissions will only ever receive the statuses + accepted or deadline_exceeded required: - freeform_id - status @@ -191,6 +203,14 @@ definitions: required: - status type: object + types.RequestSubmission: + properties: + duration_secs: + description: + Time in seconds until a task should expire. If not provided, + defaults to 3600. + type: integer + type: object types.SARIFSubmission: properties: sarif: @@ -202,7 +222,11 @@ definitions: types.SARIFSubmissionResponse: properties: status: - $ref: "#/definitions/types.SubmissionStatus" + allOf: + - $ref: "#/definitions/types.SubmissionStatus" + description: + Schema-compliant submissions will only ever receive the statuses + accepted or deadline_exceeded submitted_sarif_id: format: uuid type: string @@ -257,7 +281,7 @@ definitions: info: contact: {} title: Example Competition API - version: 1.1.1 + version: 1.2.0 paths: /v1/ping/: get: @@ -274,6 +298,46 @@ paths: summary: Test authentication creds and network connectivity tags: - ping + /v1/request/delta/: + post: + consumes: + - application/json + description: Send a delta task to the source of this request + parameters: + - description: Submission Body + in: body + name: payload + required: true + schema: + $ref: "#/definitions/types.RequestSubmission" + produces: + - application/json + responses: + "200": + description: No Content + schema: + type: string + "400": + description: Bad Request + schema: + $ref: "#/definitions/types.Error" + "401": + description: Unauthorized + schema: + $ref: "#/definitions/types.Error" + "404": + description: Not Found + schema: + $ref: "#/definitions/types.Error" + "500": + description: Internal Server Error + schema: + $ref: "#/definitions/types.Error" + security: + - BasicAuth: [] + summary: Send a delta task to the source of this request + tags: + - request /v1/task/{task_id}/broadcast-sarif-assessment/{broadcast_sarif_id}/: post: consumes: diff --git a/orchestrator/docs/api/crs-swagger-v1.2.0.json b/orchestrator/docs/api/crs-swagger-v1.2.0.json new file mode 100644 index 00000000..9ac573d3 --- /dev/null +++ b/orchestrator/docs/api/crs-swagger-v1.2.0.json @@ -0,0 +1,404 @@ +{ + "swagger": "2.0", + "info": { + "title": "Example CRS API", + "contact": {}, + "version": "1.2.0" + }, + "paths": { + "/status/": { + "get": { + "security": [ + { + "BasicAuth": [] + } + ], + "description": "report the status of the CRS", + "consumes": ["application/json"], + "produces": ["application/json"], + "tags": ["status"], + "summary": "CRS Status", + "responses": { + "200": { + "description": "Status Obect", + "schema": { + "$ref": "#/definitions/types.Status" + } + } + } + }, + "delete": { + "security": [ + { + "BasicAuth": [] + } + ], + "description": "Reset all stats in the status endpoint.", + "consumes": ["application/json"], + "produces": ["application/json"], + "tags": ["status"], + "summary": "Reset status stats", + "responses": { + "200": { + "description": "No Content", + "schema": { + "type": "string" + } + } + } + } + }, + "/v1/sarif/": { + "post": { + "security": [ + { + "BasicAuth": [] + } + ], + "description": "submit a sarif broadcast", + "consumes": ["application/json"], + "produces": ["application/json"], + "tags": ["sarif"], + "summary": "Submit Sarif Broadcast", + "parameters": [ + { + "description": "Vulnerability Broadcast", + "name": "payload", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/types.SARIFBroadcast" + } + } + ], + "responses": { + "200": { + "description": "No Content", + "schema": { + "type": "string" + } + } + } + } + }, + "/v1/task/": { + "post": { + "security": [ + { + "BasicAuth": [] + } + ], + "description": "submit a task for work", + "consumes": ["application/json"], + "produces": ["application/json"], + "tags": ["task"], + "summary": "Submit Task", + "parameters": [ + { + "description": "Submission body", + "name": "payload", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/types.Task" + } + } + ], + "responses": { + "202": { + "description": "No Content", + "schema": { + "type": "string" + } + } + } + }, + "delete": { + "security": [ + { + "BasicAuth": [] + } + ], + "description": "Cancel all previously submitted tasks. This is meant for edge case recovery in case something goes wrong.", + "consumes": ["application/json"], + "produces": ["application/json"], + "tags": ["task"], + "summary": "Cancel Tasks", + "responses": { + "200": { + "description": "No Content", + "schema": { + "type": "string" + } + } + } + } + }, + "/v1/task/{task_id}/": { + "delete": { + "security": [ + { + "BasicAuth": [] + } + ], + "description": "Cancel a task by id. This is meant for edge case recovery in case something goes wrong.", + "consumes": ["application/json"], + "produces": ["application/json"], + "tags": ["task"], + "summary": "Cancel Task", + "parameters": [ + { + "type": "string", + "format": "uuid", + "description": "Task ID", + "name": "task_id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "No Content", + "schema": { + "type": "string" + } + } + } + } + } + }, + "definitions": { + "types.SARIFBroadcast": { + "type": "object", + "required": ["broadcasts", "message_id", "message_time"], + "properties": { + "broadcasts": { + "type": "array", + "items": { + "$ref": "#/definitions/types.SARIFBroadcastDetail" + } + }, + "message_id": { + "description": "Unique ID for this message. The system will retry sending messages if it does not receive a 200 response code.\nUse this to determine if you have already processed a message.", + "type": "string", + "format": "uuid" + }, + "message_time": { + "description": "UNIX millisecond timestamp for when the message was sent", + "type": "integer" + } + } + }, + "types.SARIFBroadcastDetail": { + "type": "object", + "required": ["metadata", "sarif", "sarif_id", "task_id"], + "properties": { + "metadata": { + "description": "String to string map containing data that should be attached to outputs like log messages and OpenTelemetry trace attributes for traceability", + "type": "object" + }, + "sarif": { + "description": "SARIF Report compliant with provided schema", + "type": "object" + }, + "sarif_id": { + "type": "string", + "format": "uuid" + }, + "task_id": { + "type": "string", + "format": "uuid" + } + } + }, + "types.SourceDetail": { + "type": "object", + "required": ["sha256", "type", "url"], + "properties": { + "sha256": { + "description": "Integrity hash of the gzipped tarball", + "type": "string" + }, + "type": { + "$ref": "#/definitions/types.SourceType" + }, + "url": { + "description": "URL to fetch the source gzipped tarball", + "type": "string" + } + } + }, + "types.SourceType": { + "type": "string", + "enum": ["repo", "fuzz-tooling", "diff"], + "x-enum-varnames": [ + "SourceTypeRepo", + "SourceTypeFuzzTooling", + "SourceTypeDiff" + ] + }, + "types.Status": { + "type": "object", + "required": ["ready", "since", "state", "version"], + "properties": { + "details": { + "description": "This is optional arbitrary content that may be logged in error cases, but is mainly for interactive troubleshooting.", + "type": "object", + "additionalProperties": { + "type": "string" + } + }, + "ready": { + "description": "Boolean indicating if the CRS is prepared to work on tasks. Do not return true unless you have successfully tested connectivity to the Competition API via /v1/ping/", + "type": "boolean" + }, + "since": { + "description": "Last time task and submission stats were reset. Unix timestamp at millisecond resolution.", + "type": "integer" + }, + "state": { + "description": "State of the currently running tasks and submissions", + "allOf": [ + { + "$ref": "#/definitions/types.StatusState" + } + ] + }, + "version": { + "description": "Version string for verification and reproducibility.\n\n- git commit\n\n- SemVer\n\n- etc", + "type": "string" + } + } + }, + "types.StatusState": { + "type": "object", + "required": ["tasks"], + "properties": { + "tasks": { + "$ref": "#/definitions/types.StatusTasksState" + } + } + }, + "types.StatusTasksState": { + "type": "object", + "required": [ + "canceled", + "errored", + "failed", + "pending", + "processing", + "succeeded", + "waiting" + ], + "properties": { + "canceled": { + "description": "Number of tasks that competition infrastructure has cancelled", + "type": "integer" + }, + "errored": { + "description": "Number of tasks that the CRS encountered an unrecoverable issue for", + "type": "integer" + }, + "failed": { + "description": "Number of submissions that the competition infrastructure marked failed", + "type": "integer" + }, + "pending": { + "description": "Number of tasks that the CRS has not started work on", + "type": "integer" + }, + "processing": { + "description": "Number of tasks that the CRS is currently processing", + "type": "integer" + }, + "succeeded": { + "description": "Number of submissions that the competition infrastructure marked passed", + "type": "integer" + }, + "waiting": { + "description": "Number of submissions that the competition infrastructure is currently testing", + "type": "integer" + } + } + }, + "types.Task": { + "type": "object", + "required": ["message_id", "message_time", "tasks"], + "properties": { + "message_id": { + "description": "Unique ID for this message. The system will retry sending messages if it does not receive a 200 response code.\nUse this to determine if you have already processed a message.", + "type": "string", + "format": "uuid" + }, + "message_time": { + "description": "UNIX millisecond timestamp for when the message was sent", + "type": "integer" + }, + "tasks": { + "type": "array", + "items": { + "$ref": "#/definitions/types.TaskDetail" + } + } + } + }, + "types.TaskDetail": { + "type": "object", + "required": [ + "deadline", + "focus", + "harnesses_included", + "metadata", + "project_name", + "source", + "task_id", + "type" + ], + "properties": { + "deadline": { + "description": "UNIX millisecond timestamp by which any submissions for this task must be in", + "type": "integer" + }, + "focus": { + "description": "Because the challenge task may contain multiple repositories, the folder in the type repo source tarball containing the main project.\nIt is still set when there is only one repository.\n\nThis is the project the CRS is meant to submit vulns, patches, and SARIF assessments against.", + "type": "string" + }, + "harnesses_included": { + "type": "boolean" + }, + "metadata": { + "description": "String to string map containing data that should be attached to outputs like log messages and OpenTelemetry trace attributes for traceability", + "type": "object" + }, + "project_name": { + "description": "OSS Fuzz project name", + "type": "string" + }, + "source": { + "description": "List of sources needed to evaluate a task", + "type": "array", + "items": { + "$ref": "#/definitions/types.SourceDetail" + } + }, + "task_id": { + "type": "string", + "format": "uuid" + }, + "type": { + "$ref": "#/definitions/types.TaskType" + } + } + }, + "types.TaskType": { + "type": "string", + "enum": ["full", "delta"], + "x-enum-varnames": ["TaskTypeFull", "TaskTypeDelta"] + } + }, + "securityDefinitions": { + "BasicAuth": { + "type": "basic" + } + } +} diff --git a/orchestrator/docs/api/crs-swagger-v1.2.0.yaml b/orchestrator/docs/api/crs-swagger-v1.2.0.yaml new file mode 100644 index 00000000..9a2b3b32 --- /dev/null +++ b/orchestrator/docs/api/crs-swagger-v1.2.0.yaml @@ -0,0 +1,361 @@ +definitions: + types.SARIFBroadcast: + properties: + broadcasts: + items: + $ref: "#/definitions/types.SARIFBroadcastDetail" + type: array + message_id: + description: |- + Unique ID for this message. The system will retry sending messages if it does not receive a 200 response code. + Use this to determine if you have already processed a message. + format: uuid + type: string + message_time: + description: UNIX millisecond timestamp for when the message was sent + type: integer + required: + - broadcasts + - message_id + - message_time + type: object + types.SARIFBroadcastDetail: + properties: + metadata: + description: + String to string map containing data that should be attached + to outputs like log messages and OpenTelemetry trace attributes for traceability + type: object + sarif: + description: SARIF Report compliant with provided schema + type: object + sarif_id: + format: uuid + type: string + task_id: + format: uuid + type: string + required: + - metadata + - sarif + - sarif_id + - task_id + type: object + types.SourceDetail: + properties: + sha256: + description: Integrity hash of the gzipped tarball + type: string + type: + $ref: "#/definitions/types.SourceType" + url: + description: URL to fetch the source gzipped tarball + type: string + required: + - sha256 + - type + - url + type: object + types.SourceType: + enum: + - repo + - fuzz-tooling + - diff + type: string + x-enum-varnames: + - SourceTypeRepo + - SourceTypeFuzzTooling + - SourceTypeDiff + types.Status: + properties: + details: + additionalProperties: + type: string + description: + This is optional arbitrary content that may be logged in error + cases, but is mainly for interactive troubleshooting. + type: object + ready: + description: + Boolean indicating if the CRS is prepared to work on tasks. Do + not return true unless you have successfully tested connectivity to the + Competition API via /v1/ping/ + type: boolean + since: + description: + Last time task and submission stats were reset. Unix timestamp + at millisecond resolution. + type: integer + state: + allOf: + - $ref: "#/definitions/types.StatusState" + description: State of the currently running tasks and submissions + version: + description: |- + Version string for verification and reproducibility. + + - git commit + + - SemVer + + - etc + type: string + required: + - ready + - since + - state + - version + type: object + types.StatusState: + properties: + tasks: + $ref: "#/definitions/types.StatusTasksState" + required: + - tasks + type: object + types.StatusTasksState: + properties: + canceled: + description: Number of tasks that competition infrastructure has cancelled + type: integer + errored: + description: + Number of tasks that the CRS encountered an unrecoverable issue + for + type: integer + failed: + description: + Number of submissions that the competition infrastructure marked + failed + type: integer + pending: + description: Number of tasks that the CRS has not started work on + type: integer + processing: + description: Number of tasks that the CRS is currently processing + type: integer + succeeded: + description: + Number of submissions that the competition infrastructure marked + passed + type: integer + waiting: + description: + Number of submissions that the competition infrastructure is + currently testing + type: integer + required: + - canceled + - errored + - failed + - pending + - processing + - succeeded + - waiting + type: object + types.Task: + properties: + message_id: + description: |- + Unique ID for this message. The system will retry sending messages if it does not receive a 200 response code. + Use this to determine if you have already processed a message. + format: uuid + type: string + message_time: + description: UNIX millisecond timestamp for when the message was sent + type: integer + tasks: + items: + $ref: "#/definitions/types.TaskDetail" + type: array + required: + - message_id + - message_time + - tasks + type: object + types.TaskDetail: + properties: + deadline: + description: + UNIX millisecond timestamp by which any submissions for this + task must be in + type: integer + focus: + description: |- + Because the challenge task may contain multiple repositories, the folder in the type repo source tarball containing the main project. + It is still set when there is only one repository. + + This is the project the CRS is meant to submit vulns, patches, and SARIF assessments against. + type: string + harnesses_included: + type: boolean + metadata: + description: + String to string map containing data that should be attached + to outputs like log messages and OpenTelemetry trace attributes for traceability + type: object + project_name: + description: OSS Fuzz project name + type: string + source: + description: List of sources needed to evaluate a task + items: + $ref: "#/definitions/types.SourceDetail" + type: array + task_id: + format: uuid + type: string + type: + $ref: "#/definitions/types.TaskType" + required: + - deadline + - focus + - harnesses_included + - metadata + - project_name + - source + - task_id + - type + type: object + types.TaskType: + enum: + - full + - delta + type: string + x-enum-varnames: + - TaskTypeFull + - TaskTypeDelta +info: + contact: {} + title: Example CRS API + version: 1.2.0 +paths: + /status/: + delete: + consumes: + - application/json + description: Reset all stats in the status endpoint. + produces: + - application/json + responses: + "200": + description: No Content + schema: + type: string + security: + - BasicAuth: [] + summary: Reset status stats + tags: + - status + get: + consumes: + - application/json + description: report the status of the CRS + produces: + - application/json + responses: + "200": + description: Status Obect + schema: + $ref: "#/definitions/types.Status" + security: + - BasicAuth: [] + summary: CRS Status + tags: + - status + /v1/sarif/: + post: + consumes: + - application/json + description: submit a sarif broadcast + parameters: + - description: Vulnerability Broadcast + in: body + name: payload + required: true + schema: + $ref: "#/definitions/types.SARIFBroadcast" + produces: + - application/json + responses: + "200": + description: No Content + schema: + type: string + security: + - BasicAuth: [] + summary: Submit Sarif Broadcast + tags: + - sarif + /v1/task/: + delete: + consumes: + - application/json + description: + Cancel all previously submitted tasks. This is meant for edge case + recovery in case something goes wrong. + produces: + - application/json + responses: + "200": + description: No Content + schema: + type: string + security: + - BasicAuth: [] + summary: Cancel Tasks + tags: + - task + post: + consumes: + - application/json + description: submit a task for work + parameters: + - description: Submission body + in: body + name: payload + required: true + schema: + $ref: "#/definitions/types.Task" + produces: + - application/json + responses: + "202": + description: No Content + schema: + type: string + security: + - BasicAuth: [] + summary: Submit Task + tags: + - task + /v1/task/{task_id}/: + delete: + consumes: + - application/json + description: + Cancel a task by id. This is meant for edge case recovery in case + something goes wrong. + parameters: + - description: Task ID + format: uuid + in: path + name: task_id + required: true + type: string + produces: + - application/json + responses: + "200": + description: No Content + schema: + type: string + security: + - BasicAuth: [] + summary: Cancel Task + tags: + - task +securityDefinitions: + BasicAuth: + type: basic +swagger: "2.0" diff --git a/orchestrator/docs/api/crs-swagger.json b/orchestrator/docs/api/crs-swagger.json index d8b2c961..9ac573d3 100644 --- a/orchestrator/docs/api/crs-swagger.json +++ b/orchestrator/docs/api/crs-swagger.json @@ -3,7 +3,7 @@ "info": { "title": "Example CRS API", "contact": {}, - "version": "1.1" + "version": "1.2.0" }, "paths": { "/status/": { @@ -179,10 +179,12 @@ } }, "message_id": { + "description": "Unique ID for this message. The system will retry sending messages if it does not receive a 200 response code.\nUse this to determine if you have already processed a message.", "type": "string", "format": "uuid" }, "message_time": { + "description": "UNIX millisecond timestamp for when the message was sent", "type": "integer" } } @@ -251,7 +253,7 @@ "type": "boolean" }, "since": { - "description": "Last time task and submission stats were reset", + "description": "Last time task and submission stats were reset. Unix timestamp at millisecond resolution.", "type": "integer" }, "state": { @@ -324,10 +326,12 @@ "required": ["message_id", "message_time", "tasks"], "properties": { "message_id": { + "description": "Unique ID for this message. The system will retry sending messages if it does not receive a 200 response code.\nUse this to determine if you have already processed a message.", "type": "string", "format": "uuid" }, "message_time": { + "description": "UNIX millisecond timestamp for when the message was sent", "type": "integer" }, "tasks": { @@ -352,7 +356,7 @@ ], "properties": { "deadline": { - "description": "UNIX timestamp by which any submissions for this task must be in", + "description": "UNIX millisecond timestamp by which any submissions for this task must be in", "type": "integer" }, "focus": { diff --git a/orchestrator/docs/api/crs-swagger.yaml b/orchestrator/docs/api/crs-swagger.yaml index dc26eac3..9a2b3b32 100644 --- a/orchestrator/docs/api/crs-swagger.yaml +++ b/orchestrator/docs/api/crs-swagger.yaml @@ -6,9 +6,13 @@ definitions: $ref: "#/definitions/types.SARIFBroadcastDetail" type: array message_id: + description: |- + Unique ID for this message. The system will retry sending messages if it does not receive a 200 response code. + Use this to determine if you have already processed a message. format: uuid type: string message_time: + description: UNIX millisecond timestamp for when the message was sent type: integer required: - broadcasts @@ -78,7 +82,9 @@ definitions: Competition API via /v1/ping/ type: boolean since: - description: Last time task and submission stats were reset + description: + Last time task and submission stats were reset. Unix timestamp + at millisecond resolution. type: integer state: allOf: @@ -150,9 +156,13 @@ definitions: types.Task: properties: message_id: + description: |- + Unique ID for this message. The system will retry sending messages if it does not receive a 200 response code. + Use this to determine if you have already processed a message. format: uuid type: string message_time: + description: UNIX millisecond timestamp for when the message was sent type: integer tasks: items: @@ -167,8 +177,8 @@ definitions: properties: deadline: description: - UNIX timestamp by which any submissions for this task must be - in + UNIX millisecond timestamp by which any submissions for this + task must be in type: integer focus: description: |- @@ -218,7 +228,7 @@ definitions: info: contact: {} title: Example CRS API - version: "1.1" + version: 1.2.0 paths: /status/: delete: diff --git a/orchestrator/docs/api/sarif-schema-v1.2.0.json b/orchestrator/docs/api/sarif-schema-v1.2.0.json new file mode 100644 index 00000000..56860a0e --- /dev/null +++ b/orchestrator/docs/api/sarif-schema-v1.2.0.json @@ -0,0 +1,3315 @@ +{ + "$schema": "http://json-schema.org/draft-04/schema#", + "title": "Static Analysis Results Format (SARIF) Version 2.1.0 JSON Schema", + "id": "https://docs.oasis-open.org/sarif/sarif/v2.1.0/errata01/os/schemas/sarif-schema-2.1.0.json", + "description": "Static Analysis Results Format (SARIF) Version 2.1.0 JSON Schema: a standard format for the output of static analysis tools.", + "additionalProperties": false, + "type": "object", + "properties": { + "$schema": { + "description": "The URI of the JSON schema corresponding to the version.", + "type": "string", + "format": "uri" + }, + + "version": { + "description": "The SARIF format version of this log file.", + "enum": ["2.1.0"], + "type": "string" + }, + + "runs": { + "description": "The set of runs contained in this log file.", + "type": ["array", "null"], + "minItems": 0, + "uniqueItems": false, + "items": { + "$ref": "#/definitions/run" + } + }, + + "inlineExternalProperties": { + "description": "References to external property files that share data between runs.", + "type": "array", + "minItems": 0, + "uniqueItems": true, + "items": { + "$ref": "#/definitions/externalProperties" + } + }, + + "properties": { + "description": "Key/value pairs that provide additional information about the log file.", + "$ref": "#/definitions/propertyBag" + } + }, + + "required": ["version", "runs"], + + "definitions": { + "address": { + "description": "A physical or virtual address, or a range of addresses, in an 'addressable region' (memory or a binary file).", + "additionalProperties": false, + "type": "object", + "properties": { + "absoluteAddress": { + "description": "The address expressed as a byte offset from the start of the addressable region.", + "type": "integer", + "minimum": -1, + "default": -1 + }, + + "relativeAddress": { + "description": "The address expressed as a byte offset from the absolute address of the top-most parent object.", + "type": "integer" + }, + + "length": { + "description": "The number of bytes in this range of addresses.", + "type": "integer" + }, + + "kind": { + "description": "An open-ended string that identifies the address kind. 'data', 'function', 'header','instruction', 'module', 'page', 'section', 'segment', 'stack', 'stackFrame', 'table' are well-known values.", + "type": "string" + }, + + "name": { + "description": "A name that is associated with the address, e.g., '.text'.", + "type": "string" + }, + + "fullyQualifiedName": { + "description": "A human-readable fully qualified name that is associated with the address.", + "type": "string" + }, + + "offsetFromParent": { + "description": "The byte offset of this address from the absolute or relative address of the parent object.", + "type": "integer" + }, + + "index": { + "description": "The index within run.addresses of the cached object for this address.", + "type": "integer", + "default": -1, + "minimum": -1 + }, + + "parentIndex": { + "description": "The index within run.addresses of the parent object.", + "type": "integer", + "default": -1, + "minimum": -1 + }, + + "properties": { + "description": "Key/value pairs that provide additional information about the address.", + "$ref": "#/definitions/propertyBag" + } + } + }, + + "artifact": { + "description": "A single artifact. In some cases, this artifact might be nested within another artifact.", + "additionalProperties": false, + "type": "object", + "properties": { + "description": { + "description": "A short description of the artifact.", + "$ref": "#/definitions/message" + }, + + "location": { + "description": "The location of the artifact.", + "$ref": "#/definitions/artifactLocation" + }, + + "parentIndex": { + "description": "Identifies the index of the immediate parent of the artifact, if this artifact is nested.", + "type": "integer", + "default": -1, + "minimum": -1 + }, + + "offset": { + "description": "The offset in bytes of the artifact within its containing artifact.", + "type": "integer", + "minimum": 0 + }, + + "length": { + "description": "The length of the artifact in bytes.", + "type": "integer", + "default": -1, + "minimum": -1 + }, + + "roles": { + "description": "The role or roles played by the artifact in the analysis.", + "type": "array", + "minItems": 0, + "uniqueItems": true, + "default": [], + "items": { + "enum": [ + "analysisTarget", + "attachment", + "responseFile", + "resultFile", + "standardStream", + "tracedFile", + "unmodified", + "modified", + "added", + "deleted", + "renamed", + "uncontrolled", + "driver", + "extension", + "translation", + "taxonomy", + "policy", + "referencedOnCommandLine", + "memoryContents", + "directory", + "userSpecifiedConfiguration", + "toolSpecifiedConfiguration", + "debugOutputFile" + ], + "type": "string" + } + }, + + "mimeType": { + "description": "The MIME type (RFC 2045) of the artifact.", + "type": "string", + "pattern": "[^/]+/.+" + }, + + "contents": { + "description": "The contents of the artifact.", + "$ref": "#/definitions/artifactContent" + }, + + "encoding": { + "description": "Specifies the encoding for an artifact object that refers to a text file.", + "type": "string" + }, + + "sourceLanguage": { + "description": "Specifies the source language for any artifact object that refers to a text file that contains source code.", + "type": "string" + }, + + "hashes": { + "description": "A dictionary, each of whose keys is the name of a hash function and each of whose values is the hashed value of the artifact produced by the specified hash function.", + "type": "object", + "additionalProperties": { + "type": "string" + } + }, + + "lastModifiedTimeUtc": { + "description": "The Coordinated Universal Time (UTC) date and time at which the artifact was most recently modified. See \"Date/time properties\" in the SARIF spec for the required format.", + "type": "string", + "format": "date-time" + }, + + "properties": { + "description": "Key/value pairs that provide additional information about the artifact.", + "$ref": "#/definitions/propertyBag" + } + } + }, + + "artifactChange": { + "description": "A change to a single artifact.", + "additionalProperties": false, + "type": "object", + "properties": { + "artifactLocation": { + "description": "The location of the artifact to change.", + "$ref": "#/definitions/artifactLocation" + }, + + "replacements": { + "description": "An array of replacement objects, each of which represents the replacement of a single region in a single artifact specified by 'artifactLocation'.", + "type": "array", + "minItems": 1, + "uniqueItems": false, + "items": { + "$ref": "#/definitions/replacement" + } + }, + + "properties": { + "description": "Key/value pairs that provide additional information about the change.", + "$ref": "#/definitions/propertyBag" + } + }, + + "required": ["artifactLocation", "replacements"] + }, + + "artifactContent": { + "description": "Represents the contents of an artifact.", + "type": "object", + "additionalProperties": false, + "properties": { + "text": { + "description": "UTF-8-encoded content from a text artifact.", + "type": "string" + }, + + "binary": { + "description": "MIME Base64-encoded content from a binary artifact, or from a text artifact in its original encoding.", + "type": "string" + }, + + "rendered": { + "description": "An alternate rendered representation of the artifact (e.g., a decompiled representation of a binary region).", + "$ref": "#/definitions/multiformatMessageString" + }, + + "properties": { + "description": "Key/value pairs that provide additional information about the artifact content.", + "$ref": "#/definitions/propertyBag" + } + } + }, + + "artifactLocation": { + "description": "Specifies the location of an artifact.", + "additionalProperties": false, + "type": "object", + "properties": { + "uri": { + "description": "A string containing a valid relative or absolute URI.", + "type": "string", + "format": "uri-reference" + }, + + "uriBaseId": { + "description": "A string which indirectly specifies the absolute URI with respect to which a relative URI in the \"uri\" property is interpreted.", + "type": "string" + }, + + "index": { + "description": "The index within the run artifacts array of the artifact object associated with the artifact location.", + "type": "integer", + "default": -1, + "minimum": -1 + }, + + "description": { + "description": "A short description of the artifact location.", + "$ref": "#/definitions/message" + }, + + "properties": { + "description": "Key/value pairs that provide additional information about the artifact location.", + "$ref": "#/definitions/propertyBag" + } + } + }, + + "attachment": { + "description": "An artifact relevant to a result.", + "type": "object", + "additionalProperties": false, + "properties": { + "description": { + "description": "A message describing the role played by the attachment.", + "$ref": "#/definitions/message" + }, + + "artifactLocation": { + "description": "The location of the attachment.", + "$ref": "#/definitions/artifactLocation" + }, + + "regions": { + "description": "An array of regions of interest within the attachment.", + "type": "array", + "minItems": 0, + "uniqueItems": true, + "default": [], + "items": { + "$ref": "#/definitions/region" + } + }, + + "rectangles": { + "description": "An array of rectangles specifying areas of interest within the image.", + "type": "array", + "minItems": 0, + "uniqueItems": true, + "default": [], + "items": { + "$ref": "#/definitions/rectangle" + } + }, + + "properties": { + "description": "Key/value pairs that provide additional information about the attachment.", + "$ref": "#/definitions/propertyBag" + } + }, + + "required": ["artifactLocation"] + }, + + "codeFlow": { + "description": "A set of threadFlows which together describe a pattern of code execution relevant to detecting a result.", + "additionalProperties": false, + "type": "object", + "properties": { + "message": { + "description": "A message relevant to the code flow.", + "$ref": "#/definitions/message" + }, + + "threadFlows": { + "description": "An array of one or more unique threadFlow objects, each of which describes the progress of a program through a thread of execution.", + "type": "array", + "minItems": 1, + "uniqueItems": false, + "items": { + "$ref": "#/definitions/threadFlow" + } + }, + + "properties": { + "description": "Key/value pairs that provide additional information about the code flow.", + "$ref": "#/definitions/propertyBag" + } + }, + + "required": ["threadFlows"] + }, + + "configurationOverride": { + "description": "Information about how a specific rule or notification was reconfigured at runtime.", + "type": "object", + "additionalProperties": false, + "properties": { + "configuration": { + "description": "Specifies how the rule or notification was configured during the scan.", + "$ref": "#/definitions/reportingConfiguration" + }, + + "descriptor": { + "description": "A reference used to locate the descriptor whose configuration was overridden.", + "$ref": "#/definitions/reportingDescriptorReference" + }, + + "properties": { + "description": "Key/value pairs that provide additional information about the configuration override.", + "$ref": "#/definitions/propertyBag" + } + }, + "required": ["configuration", "descriptor"] + }, + + "conversion": { + "description": "Describes how a converter transformed the output of a static analysis tool from the analysis tool's native output format into the SARIF format.", + "additionalProperties": false, + "type": "object", + "properties": { + "tool": { + "description": "A tool object that describes the converter.", + "$ref": "#/definitions/tool" + }, + + "invocation": { + "description": "An invocation object that describes the invocation of the converter.", + "$ref": "#/definitions/invocation" + }, + + "analysisToolLogFiles": { + "description": "The locations of the analysis tool's per-run log files.", + "type": "array", + "minItems": 0, + "uniqueItems": true, + "default": [], + "items": { + "$ref": "#/definitions/artifactLocation" + } + }, + + "properties": { + "description": "Key/value pairs that provide additional information about the conversion.", + "$ref": "#/definitions/propertyBag" + } + }, + + "required": ["tool"] + }, + + "edge": { + "description": "Represents a directed edge in a graph.", + "type": "object", + "additionalProperties": false, + "properties": { + "id": { + "description": "A string that uniquely identifies the edge within its graph.", + "type": "string" + }, + + "label": { + "description": "A short description of the edge.", + "$ref": "#/definitions/message" + }, + + "sourceNodeId": { + "description": "Identifies the source node (the node at which the edge starts).", + "type": "string" + }, + + "targetNodeId": { + "description": "Identifies the target node (the node at which the edge ends).", + "type": "string" + }, + + "properties": { + "description": "Key/value pairs that provide additional information about the edge.", + "$ref": "#/definitions/propertyBag" + } + }, + + "required": ["id", "sourceNodeId", "targetNodeId"] + }, + + "edgeTraversal": { + "description": "Represents the traversal of a single edge during a graph traversal.", + "type": "object", + "additionalProperties": false, + "properties": { + "edgeId": { + "description": "Identifies the edge being traversed.", + "type": "string" + }, + + "message": { + "description": "A message to display to the user as the edge is traversed.", + "$ref": "#/definitions/message" + }, + + "finalState": { + "description": "The values of relevant expressions after the edge has been traversed.", + "type": "object", + "additionalProperties": { + "$ref": "#/definitions/multiformatMessageString" + } + }, + + "stepOverEdgeCount": { + "description": "The number of edge traversals necessary to return from a nested graph.", + "type": "integer", + "minimum": 0 + }, + + "properties": { + "description": "Key/value pairs that provide additional information about the edge traversal.", + "$ref": "#/definitions/propertyBag" + } + }, + + "required": ["edgeId"] + }, + + "exception": { + "description": "Describes a runtime exception encountered during the execution of an analysis tool.", + "type": "object", + "additionalProperties": false, + "properties": { + "kind": { + "type": "string", + "description": "A string that identifies the kind of exception, for example, the fully qualified type name of an object that was thrown, or the symbolic name of a signal." + }, + + "message": { + "description": "A message that describes the exception.", + "type": "string" + }, + + "stack": { + "description": "The sequence of function calls leading to the exception.", + "$ref": "#/definitions/stack" + }, + + "innerExceptions": { + "description": "An array of exception objects each of which is considered a cause of this exception.", + "type": "array", + "minItems": 0, + "uniqueItems": false, + "default": [], + "items": { + "$ref": "#/definitions/exception" + } + }, + + "properties": { + "description": "Key/value pairs that provide additional information about the exception.", + "$ref": "#/definitions/propertyBag" + } + } + }, + + "externalProperties": { + "description": "The top-level element of an external property file.", + "type": "object", + "additionalProperties": false, + "properties": { + "schema": { + "description": "The URI of the JSON schema corresponding to the version of the external property file format.", + "type": "string", + "format": "uri" + }, + + "version": { + "description": "The SARIF format version of this external properties object.", + "enum": ["2.1.0"], + "type": "string" + }, + + "guid": { + "description": "A stable, unique identifier for this external properties object, in the form of a GUID.", + "type": "string", + "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$" + }, + + "runGuid": { + "description": "A stable, unique identifier for the run associated with this external properties object, in the form of a GUID.", + "type": "string", + "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$" + }, + + "conversion": { + "description": "A conversion object that will be merged with a separate run.", + "$ref": "#/definitions/conversion" + }, + + "graphs": { + "description": "An array of graph objects that will be merged with a separate run.", + "type": "array", + "minItems": 0, + "default": [], + "uniqueItems": true, + "items": { + "$ref": "#/definitions/graph" + } + }, + + "externalizedProperties": { + "description": "Key/value pairs that provide additional information that will be merged with a separate run.", + "$ref": "#/definitions/propertyBag" + }, + + "artifacts": { + "description": "An array of artifact objects that will be merged with a separate run.", + "type": "array", + "minItems": 0, + "uniqueItems": true, + "items": { + "$ref": "#/definitions/artifact" + } + }, + + "invocations": { + "description": "Describes the invocation of the analysis tool that will be merged with a separate run.", + "type": "array", + "minItems": 0, + "uniqueItems": false, + "default": [], + "items": { + "$ref": "#/definitions/invocation" + } + }, + + "logicalLocations": { + "description": "An array of logical locations such as namespaces, types or functions that will be merged with a separate run.", + "type": "array", + "minItems": 0, + "uniqueItems": true, + "default": [], + "items": { + "$ref": "#/definitions/logicalLocation" + } + }, + + "threadFlowLocations": { + "description": "An array of threadFlowLocation objects that will be merged with a separate run.", + "type": "array", + "minItems": 0, + "uniqueItems": true, + "default": [], + "items": { + "$ref": "#/definitions/threadFlowLocation" + } + }, + + "results": { + "description": "An array of result objects that will be merged with a separate run.", + "type": "array", + "minItems": 0, + "uniqueItems": false, + "default": [], + "items": { + "$ref": "#/definitions/result" + } + }, + + "taxonomies": { + "description": "Tool taxonomies that will be merged with a separate run.", + "type": "array", + "minItems": 0, + "uniqueItems": true, + "default": [], + "items": { + "$ref": "#/definitions/toolComponent" + } + }, + + "driver": { + "description": "The analysis tool object that will be merged with a separate run.", + "$ref": "#/definitions/toolComponent" + }, + + "extensions": { + "description": "Tool extensions that will be merged with a separate run.", + "type": "array", + "minItems": 0, + "uniqueItems": true, + "default": [], + "items": { + "$ref": "#/definitions/toolComponent" + } + }, + + "policies": { + "description": "Tool policies that will be merged with a separate run.", + "type": "array", + "minItems": 0, + "uniqueItems": true, + "default": [], + "items": { + "$ref": "#/definitions/toolComponent" + } + }, + + "translations": { + "description": "Tool translations that will be merged with a separate run.", + "type": "array", + "minItems": 0, + "uniqueItems": true, + "default": [], + "items": { + "$ref": "#/definitions/toolComponent" + } + }, + + "addresses": { + "description": "Addresses that will be merged with a separate run.", + "type": "array", + "minItems": 0, + "uniqueItems": false, + "default": [], + "items": { + "$ref": "#/definitions/address" + } + }, + + "webRequests": { + "description": "Requests that will be merged with a separate run.", + "type": "array", + "minItems": 0, + "uniqueItems": true, + "default": [], + "items": { + "$ref": "#/definitions/webRequest" + } + }, + + "webResponses": { + "description": "Responses that will be merged with a separate run.", + "type": "array", + "minItems": 0, + "uniqueItems": true, + "default": [], + "items": { + "$ref": "#/definitions/webResponse" + } + }, + + "properties": { + "description": "Key/value pairs that provide additional information about the external properties.", + "$ref": "#/definitions/propertyBag" + } + } + }, + + "externalPropertyFileReference": { + "description": "Contains information that enables a SARIF consumer to locate the external property file that contains the value of an externalized property associated with the run.", + "type": "object", + "additionalProperties": false, + "properties": { + "location": { + "description": "The location of the external property file.", + "$ref": "#/definitions/artifactLocation" + }, + + "guid": { + "description": "A stable, unique identifier for the external property file in the form of a GUID.", + "type": "string", + "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$" + }, + + "itemCount": { + "description": "A non-negative integer specifying the number of items contained in the external property file.", + "type": "integer", + "default": -1, + "minimum": -1 + }, + + "properties": { + "description": "Key/value pairs that provide additional information about the external property file.", + "$ref": "#/definitions/propertyBag" + } + }, + "anyOf": [{ "required": ["location"] }, { "required": ["guid"] }] + }, + + "externalPropertyFileReferences": { + "description": "References to external property files that should be inlined with the content of a root log file.", + "additionalProperties": false, + "type": "object", + "properties": { + "conversion": { + "description": "An external property file containing a run.conversion object to be merged with the root log file.", + "$ref": "#/definitions/externalPropertyFileReference" + }, + + "graphs": { + "description": "An array of external property files containing a run.graphs object to be merged with the root log file.", + "type": "array", + "minItems": 0, + "uniqueItems": true, + "default": [], + "items": { + "$ref": "#/definitions/externalPropertyFileReference" + } + }, + + "externalizedProperties": { + "description": "An external property file containing a run.properties object to be merged with the root log file.", + "$ref": "#/definitions/externalPropertyFileReference" + }, + + "artifacts": { + "description": "An array of external property files containing run.artifacts arrays to be merged with the root log file.", + "type": "array", + "minItems": 0, + "uniqueItems": true, + "default": [], + "items": { + "$ref": "#/definitions/externalPropertyFileReference" + } + }, + + "invocations": { + "description": "An array of external property files containing run.invocations arrays to be merged with the root log file.", + "type": "array", + "minItems": 0, + "uniqueItems": true, + "default": [], + "items": { + "$ref": "#/definitions/externalPropertyFileReference" + } + }, + + "logicalLocations": { + "description": "An array of external property files containing run.logicalLocations arrays to be merged with the root log file.", + "type": "array", + "minItems": 0, + "uniqueItems": true, + "default": [], + "items": { + "$ref": "#/definitions/externalPropertyFileReference" + } + }, + + "threadFlowLocations": { + "description": "An array of external property files containing run.threadFlowLocations arrays to be merged with the root log file.", + "type": "array", + "minItems": 0, + "uniqueItems": true, + "default": [], + "items": { + "$ref": "#/definitions/externalPropertyFileReference" + } + }, + + "results": { + "description": "An array of external property files containing run.results arrays to be merged with the root log file.", + "type": "array", + "minItems": 0, + "uniqueItems": true, + "default": [], + "items": { + "$ref": "#/definitions/externalPropertyFileReference" + } + }, + + "taxonomies": { + "description": "An array of external property files containing run.taxonomies arrays to be merged with the root log file.", + "type": "array", + "minItems": 0, + "uniqueItems": true, + "default": [], + "items": { + "$ref": "#/definitions/externalPropertyFileReference" + } + }, + + "addresses": { + "description": "An array of external property files containing run.addresses arrays to be merged with the root log file.", + "type": "array", + "minItems": 0, + "uniqueItems": true, + "default": [], + "items": { + "$ref": "#/definitions/externalPropertyFileReference" + } + }, + + "driver": { + "description": "An external property file containing a run.driver object to be merged with the root log file.", + "$ref": "#/definitions/externalPropertyFileReference" + }, + + "extensions": { + "description": "An array of external property files containing run.extensions arrays to be merged with the root log file.", + "type": "array", + "minItems": 0, + "uniqueItems": true, + "default": [], + "items": { + "$ref": "#/definitions/externalPropertyFileReference" + } + }, + + "policies": { + "description": "An array of external property files containing run.policies arrays to be merged with the root log file.", + "type": "array", + "minItems": 0, + "uniqueItems": true, + "default": [], + "items": { + "$ref": "#/definitions/externalPropertyFileReference" + } + }, + + "translations": { + "description": "An array of external property files containing run.translations arrays to be merged with the root log file.", + "type": "array", + "minItems": 0, + "uniqueItems": true, + "default": [], + "items": { + "$ref": "#/definitions/externalPropertyFileReference" + } + }, + + "webRequests": { + "description": "An array of external property files containing run.requests arrays to be merged with the root log file.", + "type": "array", + "minItems": 0, + "uniqueItems": true, + "default": [], + "items": { + "$ref": "#/definitions/externalPropertyFileReference" + } + }, + + "webResponses": { + "description": "An array of external property files containing run.responses arrays to be merged with the root log file.", + "type": "array", + "minItems": 0, + "uniqueItems": true, + "default": [], + "items": { + "$ref": "#/definitions/externalPropertyFileReference" + } + }, + + "properties": { + "description": "Key/value pairs that provide additional information about the external property files.", + "$ref": "#/definitions/propertyBag" + } + } + }, + + "fix": { + "description": "A proposed fix for the problem represented by a result object. A fix specifies a set of artifacts to modify. For each artifact, it specifies a set of bytes to remove, and provides a set of new bytes to replace them.", + "additionalProperties": false, + "type": "object", + "properties": { + "description": { + "description": "A message that describes the proposed fix, enabling viewers to present the proposed change to an end user.", + "$ref": "#/definitions/message" + }, + + "artifactChanges": { + "description": "One or more artifact changes that comprise a fix for a result.", + "type": "array", + "minItems": 1, + "uniqueItems": true, + "items": { + "$ref": "#/definitions/artifactChange" + } + }, + + "properties": { + "description": "Key/value pairs that provide additional information about the fix.", + "$ref": "#/definitions/propertyBag" + } + }, + "required": ["artifactChanges"] + }, + + "graph": { + "description": "A network of nodes and directed edges that describes some aspect of the structure of the code (for example, a call graph).", + "type": "object", + "additionalProperties": false, + "properties": { + "description": { + "description": "A description of the graph.", + "$ref": "#/definitions/message" + }, + + "nodes": { + "description": "An array of node objects representing the nodes of the graph.", + "type": "array", + "minItems": 0, + "uniqueItems": true, + "default": [], + "items": { + "$ref": "#/definitions/node" + } + }, + + "edges": { + "description": "An array of edge objects representing the edges of the graph.", + "type": "array", + "minItems": 0, + "uniqueItems": true, + "default": [], + "items": { + "$ref": "#/definitions/edge" + } + }, + + "properties": { + "description": "Key/value pairs that provide additional information about the graph.", + "$ref": "#/definitions/propertyBag" + } + } + }, + + "graphTraversal": { + "description": "Represents a path through a graph.", + "type": "object", + "additionalProperties": false, + "properties": { + "runGraphIndex": { + "description": "The index within the run.graphs to be associated with the result.", + "type": "integer", + "default": -1, + "minimum": -1 + }, + + "resultGraphIndex": { + "description": "The index within the result.graphs to be associated with the result.", + "type": "integer", + "default": -1, + "minimum": -1 + }, + + "description": { + "description": "A description of this graph traversal.", + "$ref": "#/definitions/message" + }, + + "initialState": { + "description": "Values of relevant expressions at the start of the graph traversal that may change during graph traversal.", + "type": "object", + "additionalProperties": { + "$ref": "#/definitions/multiformatMessageString" + } + }, + + "immutableState": { + "description": "Values of relevant expressions at the start of the graph traversal that remain constant for the graph traversal.", + "type": "object", + "additionalProperties": { + "$ref": "#/definitions/multiformatMessageString" + } + }, + + "edgeTraversals": { + "description": "The sequences of edges traversed by this graph traversal.", + "type": "array", + "minItems": 0, + "uniqueItems": false, + "default": [], + "items": { + "$ref": "#/definitions/edgeTraversal" + } + }, + + "properties": { + "description": "Key/value pairs that provide additional information about the graph traversal.", + "$ref": "#/definitions/propertyBag" + } + }, + "oneOf": [ + { "required": ["runGraphIndex"] }, + { "required": ["resultGraphIndex"] } + ] + }, + + "invocation": { + "description": "The runtime environment of the analysis tool run.", + "additionalProperties": false, + "type": "object", + "properties": { + "commandLine": { + "description": "The command line used to invoke the tool.", + "type": "string" + }, + + "arguments": { + "description": "An array of strings, containing in order the command line arguments passed to the tool from the operating system.", + "type": "array", + "minItems": 0, + "uniqueItems": false, + "items": { + "type": "string" + } + }, + + "responseFiles": { + "description": "The locations of any response files specified on the tool's command line.", + "type": "array", + "minItems": 0, + "uniqueItems": true, + "items": { + "$ref": "#/definitions/artifactLocation" + } + }, + + "startTimeUtc": { + "description": "The Coordinated Universal Time (UTC) date and time at which the invocation started. See \"Date/time properties\" in the SARIF spec for the required format.", + "type": "string", + "format": "date-time" + }, + + "endTimeUtc": { + "description": "The Coordinated Universal Time (UTC) date and time at which the invocation ended. See \"Date/time properties\" in the SARIF spec for the required format.", + "type": "string", + "format": "date-time" + }, + + "exitCode": { + "description": "The process exit code.", + "type": "integer" + }, + + "ruleConfigurationOverrides": { + "description": "An array of configurationOverride objects that describe rules related runtime overrides.", + "type": "array", + "minItems": 0, + "default": [], + "uniqueItems": true, + "items": { + "$ref": "#/definitions/configurationOverride" + } + }, + + "notificationConfigurationOverrides": { + "description": "An array of configurationOverride objects that describe notifications related runtime overrides.", + "type": "array", + "minItems": 0, + "default": [], + "uniqueItems": true, + "items": { + "$ref": "#/definitions/configurationOverride" + } + }, + + "toolExecutionNotifications": { + "description": "A list of runtime conditions detected by the tool during the analysis.", + "type": "array", + "minItems": 0, + "uniqueItems": false, + "default": [], + "items": { + "$ref": "#/definitions/notification" + } + }, + + "toolConfigurationNotifications": { + "description": "A list of conditions detected by the tool that are relevant to the tool's configuration.", + "type": "array", + "minItems": 0, + "uniqueItems": false, + "default": [], + "items": { + "$ref": "#/definitions/notification" + } + }, + + "exitCodeDescription": { + "description": "The reason for the process exit.", + "type": "string" + }, + + "exitSignalName": { + "description": "The name of the signal that caused the process to exit.", + "type": "string" + }, + + "exitSignalNumber": { + "description": "The numeric value of the signal that caused the process to exit.", + "type": "integer" + }, + + "processStartFailureMessage": { + "description": "The reason given by the operating system that the process failed to start.", + "type": "string" + }, + + "executionSuccessful": { + "description": "Specifies whether the tool's execution completed successfully.", + "type": "boolean" + }, + + "machine": { + "description": "The machine on which the invocation occurred.", + "type": "string" + }, + + "account": { + "description": "The account under which the invocation occurred.", + "type": "string" + }, + + "processId": { + "description": "The id of the process in which the invocation occurred.", + "type": "integer" + }, + + "executableLocation": { + "description": "An absolute URI specifying the location of the executable that was invoked.", + "$ref": "#/definitions/artifactLocation" + }, + + "workingDirectory": { + "description": "The working directory for the invocation.", + "$ref": "#/definitions/artifactLocation" + }, + + "environmentVariables": { + "description": "The environment variables associated with the analysis tool process, expressed as key/value pairs.", + "type": "object", + "additionalProperties": { + "type": "string" + } + }, + + "stdin": { + "description": "A file containing the standard input stream to the process that was invoked.", + "$ref": "#/definitions/artifactLocation" + }, + + "stdout": { + "description": "A file containing the standard output stream from the process that was invoked.", + "$ref": "#/definitions/artifactLocation" + }, + + "stderr": { + "description": "A file containing the standard error stream from the process that was invoked.", + "$ref": "#/definitions/artifactLocation" + }, + + "stdoutStderr": { + "description": "A file containing the interleaved standard output and standard error stream from the process that was invoked.", + "$ref": "#/definitions/artifactLocation" + }, + + "properties": { + "description": "Key/value pairs that provide additional information about the invocation.", + "$ref": "#/definitions/propertyBag" + } + }, + "required": ["executionSuccessful"] + }, + + "location": { + "description": "A location within a programming artifact.", + "additionalProperties": false, + "type": "object", + "properties": { + "id": { + "description": "Value that distinguishes this location from all other locations within a single result object.", + "type": "integer", + "minimum": -1, + "default": -1 + }, + + "physicalLocation": { + "description": "Identifies the artifact and region.", + "$ref": "#/definitions/physicalLocation" + }, + + "logicalLocations": { + "description": "The logical locations associated with the result.", + "type": "array", + "minItems": 0, + "uniqueItems": true, + "default": [], + "items": { + "$ref": "#/definitions/logicalLocation" + } + }, + + "message": { + "description": "A message relevant to the location.", + "$ref": "#/definitions/message" + }, + + "annotations": { + "description": "A set of regions relevant to the location.", + "type": "array", + "minItems": 0, + "uniqueItems": true, + "default": [], + "items": { + "$ref": "#/definitions/region" + } + }, + + "relationships": { + "description": "An array of objects that describe relationships between this location and others.", + "type": "array", + "default": [], + "minItems": 0, + "uniqueItems": true, + "items": { + "$ref": "#/definitions/locationRelationship" + } + }, + + "properties": { + "description": "Key/value pairs that provide additional information about the location.", + "$ref": "#/definitions/propertyBag" + } + } + }, + + "locationRelationship": { + "description": "Information about the relation of one location to another.", + "type": "object", + "additionalProperties": false, + "properties": { + "target": { + "description": "A reference to the related location.", + "type": "integer", + "minimum": 0 + }, + + "kinds": { + "description": "A set of distinct strings that categorize the relationship. Well-known kinds include 'includes', 'isIncludedBy' and 'relevant'.", + "type": "array", + "default": ["relevant"], + "uniqueItems": true, + "items": { + "type": "string" + } + }, + + "description": { + "description": "A description of the location relationship.", + "$ref": "#/definitions/message" + }, + + "properties": { + "description": "Key/value pairs that provide additional information about the location relationship.", + "$ref": "#/definitions/propertyBag" + } + }, + "required": ["target"] + }, + + "logicalLocation": { + "description": "A logical location of a construct that produced a result.", + "additionalProperties": false, + "type": "object", + "properties": { + "name": { + "description": "Identifies the construct in which the result occurred. For example, this property might contain the name of a class or a method.", + "type": "string" + }, + + "index": { + "description": "The index within the logical locations array.", + "type": "integer", + "default": -1, + "minimum": -1 + }, + + "fullyQualifiedName": { + "description": "The human-readable fully qualified name of the logical location.", + "type": "string" + }, + + "decoratedName": { + "description": "The machine-readable name for the logical location, such as a mangled function name provided by a C++ compiler that encodes calling convention, return type and other details along with the function name.", + "type": "string" + }, + + "parentIndex": { + "description": "Identifies the index of the immediate parent of the construct in which the result was detected. For example, this property might point to a logical location that represents the namespace that holds a type.", + "type": "integer", + "default": -1, + "minimum": -1 + }, + + "kind": { + "description": "The type of construct this logical location component refers to. Should be one of 'function', 'member', 'module', 'namespace', 'parameter', 'resource', 'returnType', 'type', 'variable', 'object', 'array', 'property', 'value', 'element', 'text', 'attribute', 'comment', 'declaration', 'dtd' or 'processingInstruction', if any of those accurately describe the construct.", + "type": "string" + }, + + "properties": { + "description": "Key/value pairs that provide additional information about the logical location.", + "$ref": "#/definitions/propertyBag" + } + } + }, + + "message": { + "description": "Encapsulates a message intended to be read by the end user.", + "type": "object", + "additionalProperties": false, + + "properties": { + "text": { + "description": "A plain text message string.", + "type": "string" + }, + + "markdown": { + "description": "A Markdown message string.", + "type": "string" + }, + + "id": { + "description": "The identifier for this message.", + "type": "string" + }, + + "arguments": { + "description": "An array of strings to substitute into the message string.", + "type": "array", + "minItems": 0, + "uniqueItems": false, + "default": [], + "items": { + "type": "string" + } + }, + + "properties": { + "description": "Key/value pairs that provide additional information about the message.", + "$ref": "#/definitions/propertyBag" + } + }, + "anyOf": [{ "required": ["text"] }, { "required": ["id"] }] + }, + + "multiformatMessageString": { + "description": "A message string or message format string rendered in multiple formats.", + "type": "object", + "additionalProperties": false, + + "properties": { + "text": { + "description": "A plain text message string or format string.", + "type": "string" + }, + + "markdown": { + "description": "A Markdown message string or format string.", + "type": "string" + }, + + "properties": { + "description": "Key/value pairs that provide additional information about the message.", + "$ref": "#/definitions/propertyBag" + } + }, + "required": ["text"] + }, + + "node": { + "description": "Represents a node in a graph.", + "type": "object", + "additionalProperties": false, + + "properties": { + "id": { + "description": "A string that uniquely identifies the node within its graph.", + "type": "string" + }, + + "label": { + "description": "A short description of the node.", + "$ref": "#/definitions/message" + }, + + "location": { + "description": "A code location associated with the node.", + "$ref": "#/definitions/location" + }, + + "children": { + "description": "Array of child nodes.", + "type": "array", + "minItems": 0, + "uniqueItems": true, + "default": [], + "items": { + "$ref": "#/definitions/node" + } + }, + + "properties": { + "description": "Key/value pairs that provide additional information about the node.", + "$ref": "#/definitions/propertyBag" + } + }, + + "required": ["id"] + }, + + "notification": { + "description": "Describes a condition relevant to the tool itself, as opposed to being relevant to a target being analyzed by the tool.", + "type": "object", + "additionalProperties": false, + "properties": { + "locations": { + "description": "The locations relevant to this notification.", + "type": "array", + "minItems": 0, + "uniqueItems": true, + "default": [], + "items": { + "$ref": "#/definitions/location" + } + }, + + "message": { + "description": "A message that describes the condition that was encountered.", + "$ref": "#/definitions/message" + }, + + "level": { + "description": "A value specifying the severity level of the notification.", + "default": "warning", + "enum": ["none", "note", "warning", "error"], + "type": "string" + }, + + "threadId": { + "description": "The thread identifier of the code that generated the notification.", + "type": "integer" + }, + + "timeUtc": { + "description": "The Coordinated Universal Time (UTC) date and time at which the analysis tool generated the notification.", + "type": "string", + "format": "date-time" + }, + + "exception": { + "description": "The runtime exception, if any, relevant to this notification.", + "$ref": "#/definitions/exception" + }, + + "descriptor": { + "description": "A reference used to locate the descriptor relevant to this notification.", + "$ref": "#/definitions/reportingDescriptorReference" + }, + + "associatedRule": { + "description": "A reference used to locate the rule descriptor associated with this notification.", + "$ref": "#/definitions/reportingDescriptorReference" + }, + + "properties": { + "description": "Key/value pairs that provide additional information about the notification.", + "$ref": "#/definitions/propertyBag" + } + }, + + "required": ["message"] + }, + + "physicalLocation": { + "description": "A physical location relevant to a result. Specifies a reference to a programming artifact together with a range of bytes or characters within that artifact.", + "additionalProperties": false, + "type": "object", + "properties": { + "address": { + "description": "The address of the location.", + "$ref": "#/definitions/address" + }, + + "artifactLocation": { + "description": "The location of the artifact.", + "$ref": "#/definitions/artifactLocation" + }, + + "region": { + "description": "Specifies a portion of the artifact.", + "$ref": "#/definitions/region" + }, + + "contextRegion": { + "description": "Specifies a portion of the artifact that encloses the region. Allows a viewer to display additional context around the region.", + "$ref": "#/definitions/region" + }, + + "properties": { + "description": "Key/value pairs that provide additional information about the physical location.", + "$ref": "#/definitions/propertyBag" + } + }, + + "anyOf": [ + { + "required": ["address"] + }, + { + "required": ["artifactLocation"] + } + ] + }, + + "propertyBag": { + "description": "Key/value pairs that provide additional information about the object.", + "type": "object", + "additionalProperties": true, + "properties": { + "tags": { + "description": "A set of distinct strings that provide additional information.", + "type": "array", + "minItems": 0, + "uniqueItems": true, + "default": [], + "items": { + "type": "string" + } + } + } + }, + + "rectangle": { + "description": "An area within an image.", + "additionalProperties": false, + "type": "object", + "properties": { + "top": { + "description": "The Y coordinate of the top edge of the rectangle, measured in the image's natural units.", + "type": "number" + }, + + "left": { + "description": "The X coordinate of the left edge of the rectangle, measured in the image's natural units.", + "type": "number" + }, + + "bottom": { + "description": "The Y coordinate of the bottom edge of the rectangle, measured in the image's natural units.", + "type": "number" + }, + + "right": { + "description": "The X coordinate of the right edge of the rectangle, measured in the image's natural units.", + "type": "number" + }, + + "message": { + "description": "A message relevant to the rectangle.", + "$ref": "#/definitions/message" + }, + + "properties": { + "description": "Key/value pairs that provide additional information about the rectangle.", + "$ref": "#/definitions/propertyBag" + } + } + }, + + "region": { + "description": "A region within an artifact where a result was detected.", + "additionalProperties": false, + "type": "object", + "properties": { + "startLine": { + "description": "The line number of the first character in the region.", + "type": "integer", + "minimum": 1 + }, + + "startColumn": { + "description": "The column number of the first character in the region.", + "type": "integer", + "minimum": 1 + }, + + "endLine": { + "description": "The line number of the last character in the region.", + "type": "integer", + "minimum": 1 + }, + + "endColumn": { + "description": "The column number of the character following the end of the region.", + "type": "integer", + "minimum": 1 + }, + + "charOffset": { + "description": "The zero-based offset from the beginning of the artifact of the first character in the region.", + "type": "integer", + "default": -1, + "minimum": -1 + }, + + "charLength": { + "description": "The length of the region in characters.", + "type": "integer", + "minimum": 0 + }, + + "byteOffset": { + "description": "The zero-based offset from the beginning of the artifact of the first byte in the region.", + "type": "integer", + "default": -1, + "minimum": -1 + }, + + "byteLength": { + "description": "The length of the region in bytes.", + "type": "integer", + "minimum": 0 + }, + + "snippet": { + "description": "The portion of the artifact contents within the specified region.", + "$ref": "#/definitions/artifactContent" + }, + + "message": { + "description": "A message relevant to the region.", + "$ref": "#/definitions/message" + }, + + "sourceLanguage": { + "description": "Specifies the source language, if any, of the portion of the artifact specified by the region object.", + "type": "string" + }, + + "properties": { + "description": "Key/value pairs that provide additional information about the region.", + "$ref": "#/definitions/propertyBag" + } + }, + + "anyOf": [ + { "required": ["startLine"] }, + { "required": ["charOffset"] }, + { "required": ["byteOffset"] } + ] + }, + + "replacement": { + "description": "The replacement of a single region of an artifact.", + "additionalProperties": false, + "type": "object", + "properties": { + "deletedRegion": { + "description": "The region of the artifact to delete.", + "$ref": "#/definitions/region" + }, + + "insertedContent": { + "description": "The content to insert at the location specified by the 'deletedRegion' property.", + "$ref": "#/definitions/artifactContent" + }, + + "properties": { + "description": "Key/value pairs that provide additional information about the replacement.", + "$ref": "#/definitions/propertyBag" + } + }, + + "required": ["deletedRegion"] + }, + + "reportingDescriptor": { + "description": "Metadata that describes a specific report produced by the tool, as part of the analysis it provides or its runtime reporting.", + "additionalProperties": false, + "type": "object", + "properties": { + "id": { + "description": "A stable, opaque identifier for the report.", + "type": "string" + }, + + "deprecatedIds": { + "description": "An array of stable, opaque identifiers by which this report was known in some previous version of the analysis tool.", + "type": "array", + "minItems": 0, + "uniqueItems": true, + "items": { + "type": "string" + } + }, + + "guid": { + "description": "A unique identifier for the reporting descriptor in the form of a GUID.", + "type": "string", + "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$" + }, + + "deprecatedGuids": { + "description": "An array of unique identifies in the form of a GUID by which this report was known in some previous version of the analysis tool.", + "type": "array", + "minItems": 0, + "uniqueItems": true, + "items": { + "type": "string", + "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$" + } + }, + + "name": { + "description": "A report identifier that is understandable to an end user.", + "type": "string" + }, + + "deprecatedNames": { + "description": "An array of readable identifiers by which this report was known in some previous version of the analysis tool.", + "type": "array", + "minItems": 0, + "uniqueItems": true, + "items": { + "type": "string" + } + }, + + "shortDescription": { + "description": "A concise description of the report. Should be a single sentence that is understandable when visible space is limited to a single line of text.", + "$ref": "#/definitions/multiformatMessageString" + }, + + "fullDescription": { + "description": "A description of the report. Should, as far as possible, provide details sufficient to enable resolution of any problem indicated by the result.", + "$ref": "#/definitions/multiformatMessageString" + }, + + "messageStrings": { + "description": "A set of name/value pairs with arbitrary names. Each value is a multiformatMessageString object, which holds message strings in plain text and (optionally) Markdown format. The strings can include placeholders, which can be used to construct a message in combination with an arbitrary number of additional string arguments.", + "type": "object", + "additionalProperties": { + "$ref": "#/definitions/multiformatMessageString" + } + }, + + "defaultConfiguration": { + "description": "Default reporting configuration information.", + "$ref": "#/definitions/reportingConfiguration" + }, + + "helpUri": { + "description": "A URI where the primary documentation for the report can be found.", + "type": "string", + "format": "uri" + }, + + "help": { + "description": "Provides the primary documentation for the report, useful when there is no online documentation.", + "$ref": "#/definitions/multiformatMessageString" + }, + + "relationships": { + "description": "An array of objects that describe relationships between this reporting descriptor and others.", + "type": "array", + "default": [], + "minItems": 0, + "uniqueItems": true, + "items": { + "$ref": "#/definitions/reportingDescriptorRelationship" + } + }, + + "properties": { + "description": "Key/value pairs that provide additional information about the report.", + "$ref": "#/definitions/propertyBag" + } + }, + "required": ["id"] + }, + + "reportingConfiguration": { + "description": "Information about a rule or notification that can be configured at runtime.", + "type": "object", + "additionalProperties": false, + "properties": { + "enabled": { + "description": "Specifies whether the report may be produced during the scan.", + "type": "boolean", + "default": true + }, + + "level": { + "description": "Specifies the failure level for the report.", + "default": "warning", + "enum": ["none", "note", "warning", "error"], + "type": "string" + }, + + "rank": { + "description": "Specifies the relative priority of the report. Used for analysis output only.", + "type": "number", + "default": -1.0, + "minimum": -1.0, + "maximum": 100.0 + }, + + "parameters": { + "description": "Contains configuration information specific to a report.", + "$ref": "#/definitions/propertyBag" + }, + + "properties": { + "description": "Key/value pairs that provide additional information about the reporting configuration.", + "$ref": "#/definitions/propertyBag" + } + } + }, + + "reportingDescriptorReference": { + "description": "Information about how to locate a relevant reporting descriptor.", + "type": "object", + "additionalProperties": false, + "properties": { + "id": { + "description": "The id of the descriptor.", + "type": "string" + }, + + "index": { + "description": "The index into an array of descriptors in toolComponent.ruleDescriptors, toolComponent.notificationDescriptors, or toolComponent.taxonomyDescriptors, depending on context.", + "type": "integer", + "default": -1, + "minimum": -1 + }, + + "guid": { + "description": "A guid that uniquely identifies the descriptor.", + "type": "string", + "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$" + }, + + "toolComponent": { + "description": "A reference used to locate the toolComponent associated with the descriptor.", + "$ref": "#/definitions/toolComponentReference" + }, + + "properties": { + "description": "Key/value pairs that provide additional information about the reporting descriptor reference.", + "$ref": "#/definitions/propertyBag" + } + }, + "anyOf": [ + { "required": ["index"] }, + { "required": ["guid"] }, + { "required": ["id"] } + ] + }, + + "reportingDescriptorRelationship": { + "description": "Information about the relation of one reporting descriptor to another.", + "type": "object", + "additionalProperties": false, + "properties": { + "target": { + "description": "A reference to the related reporting descriptor.", + "$ref": "#/definitions/reportingDescriptorReference" + }, + + "kinds": { + "description": "A set of distinct strings that categorize the relationship. Well-known kinds include 'canPrecede', 'canFollow', 'willPrecede', 'willFollow', 'superset', 'subset', 'equal', 'disjoint', 'relevant', and 'incomparable'.", + "type": "array", + "default": ["relevant"], + "uniqueItems": true, + "items": { + "type": "string" + } + }, + + "description": { + "description": "A description of the reporting descriptor relationship.", + "$ref": "#/definitions/message" + }, + + "properties": { + "description": "Key/value pairs that provide additional information about the reporting descriptor reference.", + "$ref": "#/definitions/propertyBag" + } + }, + "required": ["target"] + }, + + "result": { + "description": "A result produced by an analysis tool.", + "additionalProperties": false, + "type": "object", + "properties": { + "ruleId": { + "description": "The stable, unique identifier of the rule, if any, to which this result is relevant.", + "type": "string" + }, + + "ruleIndex": { + "description": "The index within the tool component rules array of the rule object associated with this result.", + "type": "integer", + "default": -1, + "minimum": -1 + }, + + "rule": { + "description": "A reference used to locate the rule descriptor relevant to this result.", + "$ref": "#/definitions/reportingDescriptorReference" + }, + + "kind": { + "description": "A value that categorizes results by evaluation state.", + "default": "fail", + "enum": [ + "notApplicable", + "pass", + "fail", + "review", + "open", + "informational" + ], + "type": "string" + }, + + "level": { + "description": "A value specifying the severity level of the result.", + "default": "warning", + "enum": ["none", "note", "warning", "error"], + "type": "string" + }, + + "message": { + "description": "A message that describes the result. The first sentence of the message only will be displayed when visible space is limited.", + "$ref": "#/definitions/message" + }, + + "analysisTarget": { + "description": "Identifies the artifact that the analysis tool was instructed to scan. This need not be the same as the artifact where the result actually occurred.", + "$ref": "#/definitions/artifactLocation" + }, + + "locations": { + "description": "The set of locations where the result was detected. Specify only one location unless the problem indicated by the result can only be corrected by making a change at every specified location.", + "type": "array", + "minItems": 0, + "uniqueItems": false, + "default": [], + "items": { + "$ref": "#/definitions/location" + } + }, + + "guid": { + "description": "A stable, unique identifier for the result in the form of a GUID.", + "type": "string", + "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$" + }, + + "correlationGuid": { + "description": "A stable, unique identifier for the equivalence class of logically identical results to which this result belongs, in the form of a GUID.", + "type": "string", + "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$" + }, + + "occurrenceCount": { + "description": "A positive integer specifying the number of times this logically unique result was observed in this run.", + "type": "integer", + "minimum": 1 + }, + + "partialFingerprints": { + "description": "A set of strings that contribute to the stable, unique identity of the result.", + "type": "object", + "additionalProperties": { + "type": "string" + } + }, + + "fingerprints": { + "description": "A set of strings each of which individually defines a stable, unique identity for the result.", + "type": "object", + "additionalProperties": { + "type": "string" + } + }, + + "stacks": { + "description": "An array of 'stack' objects relevant to the result.", + "type": "array", + "minItems": 0, + "uniqueItems": true, + "default": [], + "items": { + "$ref": "#/definitions/stack" + } + }, + + "codeFlows": { + "description": "An array of 'codeFlow' objects relevant to the result.", + "type": "array", + "minItems": 0, + "uniqueItems": false, + "default": [], + "items": { + "$ref": "#/definitions/codeFlow" + } + }, + + "graphs": { + "description": "An array of zero or more unique graph objects associated with the result.", + "type": "array", + "minItems": 0, + "uniqueItems": true, + "default": [], + "items": { + "$ref": "#/definitions/graph" + } + }, + + "graphTraversals": { + "description": "An array of one or more unique 'graphTraversal' objects.", + "type": "array", + "minItems": 0, + "uniqueItems": true, + "default": [], + "items": { + "$ref": "#/definitions/graphTraversal" + } + }, + + "relatedLocations": { + "description": "A set of locations relevant to this result.", + "type": "array", + "minItems": 0, + "uniqueItems": true, + "default": [], + "items": { + "$ref": "#/definitions/location" + } + }, + + "suppressions": { + "description": "A set of suppressions relevant to this result.", + "type": "array", + "minItems": 0, + "uniqueItems": true, + "items": { + "$ref": "#/definitions/suppression" + } + }, + + "baselineState": { + "description": "The state of a result relative to a baseline of a previous run.", + "enum": ["new", "unchanged", "updated", "absent"], + "type": "string" + }, + + "rank": { + "description": "A number representing the priority or importance of the result.", + "type": "number", + "default": -1.0, + "minimum": -1.0, + "maximum": 100.0 + }, + + "attachments": { + "description": "A set of artifacts relevant to the result.", + "type": "array", + "minItems": 0, + "uniqueItems": true, + "default": [], + "items": { + "$ref": "#/definitions/attachment" + } + }, + + "hostedViewerUri": { + "description": "An absolute URI at which the result can be viewed.", + "type": "string", + "format": "uri" + }, + + "workItemUris": { + "description": "The URIs of the work items associated with this result.", + "type": "array", + "minItems": 0, + "uniqueItems": true, + "items": { + "type": "string", + "format": "uri" + } + }, + + "provenance": { + "description": "Information about how and when the result was detected.", + "$ref": "#/definitions/resultProvenance" + }, + + "fixes": { + "description": "An array of 'fix' objects, each of which represents a proposed fix to the problem indicated by the result.", + "type": "array", + "minItems": 0, + "uniqueItems": true, + "default": [], + "items": { + "$ref": "#/definitions/fix" + } + }, + + "taxa": { + "description": "An array of references to taxonomy reporting descriptors that are applicable to the result.", + "type": "array", + "default": [], + "minItems": 0, + "uniqueItems": true, + "items": { + "$ref": "#/definitions/reportingDescriptorReference" + } + }, + + "webRequest": { + "description": "A web request associated with this result.", + "$ref": "#/definitions/webRequest" + }, + + "webResponse": { + "description": "A web response associated with this result.", + "$ref": "#/definitions/webResponse" + }, + + "properties": { + "description": "Key/value pairs that provide additional information about the result.", + "$ref": "#/definitions/propertyBag" + } + }, + "required": ["message"] + }, + + "resultProvenance": { + "description": "Contains information about how and when a result was detected.", + "additionalProperties": false, + "type": "object", + "properties": { + "firstDetectionTimeUtc": { + "description": "The Coordinated Universal Time (UTC) date and time at which the result was first detected. See \"Date/time properties\" in the SARIF spec for the required format.", + "type": "string", + "format": "date-time" + }, + + "lastDetectionTimeUtc": { + "description": "The Coordinated Universal Time (UTC) date and time at which the result was most recently detected. See \"Date/time properties\" in the SARIF spec for the required format.", + "type": "string", + "format": "date-time" + }, + + "firstDetectionRunGuid": { + "description": "A GUID-valued string equal to the automationDetails.guid property of the run in which the result was first detected.", + "type": "string", + "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$" + }, + + "lastDetectionRunGuid": { + "description": "A GUID-valued string equal to the automationDetails.guid property of the run in which the result was most recently detected.", + "type": "string", + "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$" + }, + + "invocationIndex": { + "description": "The index within the run.invocations array of the invocation object which describes the tool invocation that detected the result.", + "type": "integer", + "default": -1, + "minimum": -1 + }, + + "conversionSources": { + "description": "An array of physicalLocation objects which specify the portions of an analysis tool's output that a converter transformed into the result.", + "type": "array", + "minItems": 0, + "uniqueItems": true, + "default": [], + "items": { + "$ref": "#/definitions/physicalLocation" + } + }, + + "properties": { + "description": "Key/value pairs that provide additional information about the result.", + "$ref": "#/definitions/propertyBag" + } + } + }, + + "run": { + "description": "Describes a single run of an analysis tool, and contains the reported output of that run.", + "additionalProperties": false, + "type": "object", + "properties": { + "tool": { + "description": "Information about the tool or tool pipeline that generated the results in this run. A run can only contain results produced by a single tool or tool pipeline. A run can aggregate results from multiple log files, as long as context around the tool run (tool command-line arguments and the like) is identical for all aggregated files.", + "$ref": "#/definitions/tool" + }, + + "invocations": { + "description": "Describes the invocation of the analysis tool.", + "type": "array", + "minItems": 0, + "uniqueItems": false, + "default": [], + "items": { + "$ref": "#/definitions/invocation" + } + }, + + "conversion": { + "description": "A conversion object that describes how a converter transformed an analysis tool's native reporting format into the SARIF format.", + "$ref": "#/definitions/conversion" + }, + + "language": { + "description": "The language of the messages emitted into the log file during this run (expressed as an ISO 639-1 two-letter lowercase culture code) and an optional region (expressed as an ISO 3166-1 two-letter uppercase subculture code associated with a country or region). The casing is recommended but not required (in order for this data to conform to RFC5646).", + "type": "string", + "default": "en-US", + "pattern": "^[a-zA-Z]{2}(-[a-zA-Z]{2})?$" + }, + + "versionControlProvenance": { + "description": "Specifies the revision in version control of the artifacts that were scanned.", + "type": "array", + "minItems": 0, + "uniqueItems": true, + "default": [], + "items": { + "$ref": "#/definitions/versionControlDetails" + } + }, + + "originalUriBaseIds": { + "description": "The artifact location specified by each uriBaseId symbol on the machine where the tool originally ran.", + "type": "object", + "additionalProperties": { + "$ref": "#/definitions/artifactLocation" + } + }, + + "artifacts": { + "description": "An array of artifact objects relevant to the run.", + "type": "array", + "minItems": 0, + "uniqueItems": true, + "items": { + "$ref": "#/definitions/artifact" + } + }, + + "logicalLocations": { + "description": "An array of logical locations such as namespaces, types or functions.", + "type": "array", + "minItems": 0, + "uniqueItems": true, + "default": [], + "items": { + "$ref": "#/definitions/logicalLocation" + } + }, + + "graphs": { + "description": "An array of zero or more unique graph objects associated with the run.", + "type": "array", + "minItems": 0, + "uniqueItems": true, + "default": [], + "items": { + "$ref": "#/definitions/graph" + } + }, + + "results": { + "description": "The set of results contained in an SARIF log. The results array can be omitted when a run is solely exporting rules metadata. It must be present (but may be empty) if a log file represents an actual scan.", + "type": "array", + "minItems": 0, + "uniqueItems": false, + "items": { + "$ref": "#/definitions/result" + } + }, + + "automationDetails": { + "description": "Automation details that describe this run.", + "$ref": "#/definitions/runAutomationDetails" + }, + + "runAggregates": { + "description": "Automation details that describe the aggregate of runs to which this run belongs.", + "type": "array", + "minItems": 0, + "uniqueItems": true, + "default": [], + "items": { + "$ref": "#/definitions/runAutomationDetails" + } + }, + + "baselineGuid": { + "description": "The 'guid' property of a previous SARIF 'run' that comprises the baseline that was used to compute result 'baselineState' properties for the run.", + "type": "string", + "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$" + }, + + "redactionTokens": { + "description": "An array of strings used to replace sensitive information in a redaction-aware property.", + "type": "array", + "minItems": 0, + "uniqueItems": true, + "default": [], + "items": { + "type": "string" + } + }, + + "defaultEncoding": { + "description": "Specifies the default encoding for any artifact object that refers to a text file.", + "type": "string" + }, + + "defaultSourceLanguage": { + "description": "Specifies the default source language for any artifact object that refers to a text file that contains source code.", + "type": "string" + }, + + "newlineSequences": { + "description": "An ordered list of character sequences that were treated as line breaks when computing region information for the run.", + "type": "array", + "minItems": 1, + "uniqueItems": true, + "default": ["\r\n", "\n"], + "items": { + "type": "string" + } + }, + + "columnKind": { + "description": "Specifies the unit in which the tool measures columns.", + "enum": ["utf16CodeUnits", "unicodeCodePoints"], + "type": "string" + }, + + "externalPropertyFileReferences": { + "description": "References to external property files that should be inlined with the content of a root log file.", + "$ref": "#/definitions/externalPropertyFileReferences" + }, + + "threadFlowLocations": { + "description": "An array of threadFlowLocation objects cached at run level.", + "type": "array", + "minItems": 0, + "uniqueItems": true, + "default": [], + "items": { + "$ref": "#/definitions/threadFlowLocation" + } + }, + + "taxonomies": { + "description": "An array of toolComponent objects relevant to a taxonomy in which results are categorized.", + "type": "array", + "minItems": 0, + "uniqueItems": true, + "default": [], + "items": { + "$ref": "#/definitions/toolComponent" + } + }, + + "addresses": { + "description": "Addresses associated with this run instance, if any.", + "type": "array", + "minItems": 0, + "uniqueItems": false, + "default": [], + "items": { + "$ref": "#/definitions/address" + } + }, + + "translations": { + "description": "The set of available translations of the localized data provided by the tool.", + "type": "array", + "minItems": 0, + "uniqueItems": true, + "default": [], + "items": { + "$ref": "#/definitions/toolComponent" + } + }, + + "policies": { + "description": "Contains configurations that may potentially override both reportingDescriptor.defaultConfiguration (the tool's default severities) and invocation.configurationOverrides (severities established at run-time from the command line).", + "type": "array", + "minItems": 0, + "uniqueItems": true, + "default": [], + "items": { + "$ref": "#/definitions/toolComponent" + } + }, + + "webRequests": { + "description": "An array of request objects cached at run level.", + "type": "array", + "minItems": 0, + "uniqueItems": true, + "default": [], + "items": { + "$ref": "#/definitions/webRequest" + } + }, + + "webResponses": { + "description": "An array of response objects cached at run level.", + "type": "array", + "minItems": 0, + "uniqueItems": true, + "default": [], + "items": { + "$ref": "#/definitions/webResponse" + } + }, + + "specialLocations": { + "description": "A specialLocations object that defines locations of special significance to SARIF consumers.", + "$ref": "#/definitions/specialLocations" + }, + + "properties": { + "description": "Key/value pairs that provide additional information about the run.", + "$ref": "#/definitions/propertyBag" + } + }, + + "required": ["tool"] + }, + + "runAutomationDetails": { + "description": "Information that describes a run's identity and role within an engineering system process.", + "additionalProperties": false, + "type": "object", + "properties": { + "description": { + "description": "A description of the identity and role played within the engineering system by this object's containing run object.", + "$ref": "#/definitions/message" + }, + + "id": { + "description": "A hierarchical string that uniquely identifies this object's containing run object.", + "type": "string" + }, + + "guid": { + "description": "A stable, unique identifier for this object's containing run object in the form of a GUID.", + "type": "string", + "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$" + }, + + "correlationGuid": { + "description": "A stable, unique identifier for the equivalence class of runs to which this object's containing run object belongs in the form of a GUID.", + "type": "string", + "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$" + }, + + "properties": { + "description": "Key/value pairs that provide additional information about the run automation details.", + "$ref": "#/definitions/propertyBag" + } + } + }, + + "specialLocations": { + "description": "Defines locations of special significance to SARIF consumers.", + "type": "object", + "additionalProperties": false, + "properties": { + "displayBase": { + "description": "Provides a suggestion to SARIF consumers to display file paths relative to the specified location.", + "$ref": "#/definitions/artifactLocation" + }, + + "properties": { + "description": "Key/value pairs that provide additional information about the special locations.", + "$ref": "#/definitions/propertyBag" + } + } + }, + + "stack": { + "description": "A call stack that is relevant to a result.", + "additionalProperties": false, + "type": "object", + "properties": { + "message": { + "description": "A message relevant to this call stack.", + "$ref": "#/definitions/message" + }, + + "frames": { + "description": "An array of stack frames that represents a sequence of calls, rendered in reverse chronological order, that comprise the call stack.", + "type": "array", + "minItems": 0, + "uniqueItems": false, + "items": { + "$ref": "#/definitions/stackFrame" + } + }, + + "properties": { + "description": "Key/value pairs that provide additional information about the stack.", + "$ref": "#/definitions/propertyBag" + } + }, + "required": ["frames"] + }, + + "stackFrame": { + "description": "A function call within a stack trace.", + "additionalProperties": false, + "type": "object", + "properties": { + "location": { + "description": "The location to which this stack frame refers.", + "$ref": "#/definitions/location" + }, + + "module": { + "description": "The name of the module that contains the code of this stack frame.", + "type": "string" + }, + + "threadId": { + "description": "The thread identifier of the stack frame.", + "type": "integer" + }, + + "parameters": { + "description": "The parameters of the call that is executing.", + "type": "array", + "minItems": 0, + "uniqueItems": false, + "default": [], + "items": { + "type": "string", + "default": [] + } + }, + + "properties": { + "description": "Key/value pairs that provide additional information about the stack frame.", + "$ref": "#/definitions/propertyBag" + } + } + }, + + "suppression": { + "description": "A suppression that is relevant to a result.", + "additionalProperties": false, + "type": "object", + "properties": { + "guid": { + "description": "A stable, unique identifier for the suprression in the form of a GUID.", + "type": "string", + "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$" + }, + + "kind": { + "description": "A string that indicates where the suppression is persisted.", + "enum": ["inSource", "external"], + "type": "string" + }, + + "status": { + "description": "A string that indicates the review status of the suppression.", + "enum": ["accepted", "underReview", "rejected"], + "type": "string" + }, + + "justification": { + "description": "A string representing the justification for the suppression.", + "type": "string" + }, + + "location": { + "description": "Identifies the location associated with the suppression.", + "$ref": "#/definitions/location" + }, + + "properties": { + "description": "Key/value pairs that provide additional information about the suppression.", + "$ref": "#/definitions/propertyBag" + } + }, + "required": ["kind"] + }, + + "threadFlow": { + "description": "Describes a sequence of code locations that specify a path through a single thread of execution such as an operating system or fiber.", + "type": "object", + "additionalProperties": false, + "properties": { + "id": { + "description": "An string that uniquely identifies the threadFlow within the codeFlow in which it occurs.", + "type": "string" + }, + + "message": { + "description": "A message relevant to the thread flow.", + "$ref": "#/definitions/message" + }, + + "initialState": { + "description": "Values of relevant expressions at the start of the thread flow that may change during thread flow execution.", + "type": "object", + "additionalProperties": { + "$ref": "#/definitions/multiformatMessageString" + } + }, + + "immutableState": { + "description": "Values of relevant expressions at the start of the thread flow that remain constant.", + "type": "object", + "additionalProperties": { + "$ref": "#/definitions/multiformatMessageString" + } + }, + + "locations": { + "description": "A temporally ordered array of 'threadFlowLocation' objects, each of which describes a location visited by the tool while producing the result.", + "type": "array", + "minItems": 1, + "uniqueItems": false, + "items": { + "$ref": "#/definitions/threadFlowLocation" + } + }, + + "properties": { + "description": "Key/value pairs that provide additional information about the thread flow.", + "$ref": "#/definitions/propertyBag" + } + }, + + "required": ["locations"] + }, + + "threadFlowLocation": { + "description": "A location visited by an analysis tool while simulating or monitoring the execution of a program.", + "additionalProperties": false, + "type": "object", + "properties": { + "index": { + "description": "The index within the run threadFlowLocations array.", + "type": "integer", + "default": -1, + "minimum": -1 + }, + + "location": { + "description": "The code location.", + "$ref": "#/definitions/location" + }, + + "stack": { + "description": "The call stack leading to this location.", + "$ref": "#/definitions/stack" + }, + + "kinds": { + "description": "A set of distinct strings that categorize the thread flow location. Well-known kinds include 'acquire', 'release', 'enter', 'exit', 'call', 'return', 'branch', 'implicit', 'false', 'true', 'caution', 'danger', 'unknown', 'unreachable', 'taint', 'function', 'handler', 'lock', 'memory', 'resource', 'scope' and 'value'.", + "type": "array", + "minItems": 0, + "uniqueItems": true, + "default": [], + "items": { + "type": "string" + } + }, + + "taxa": { + "description": "An array of references to rule or taxonomy reporting descriptors that are applicable to the thread flow location.", + "type": "array", + "default": [], + "minItems": 0, + "uniqueItems": true, + "items": { + "$ref": "#/definitions/reportingDescriptorReference" + } + }, + + "module": { + "description": "The name of the module that contains the code that is executing.", + "type": "string" + }, + + "state": { + "description": "A dictionary, each of whose keys specifies a variable or expression, the associated value of which represents the variable or expression value. For an annotation of kind 'continuation', for example, this dictionary might hold the current assumed values of a set of global variables.", + "type": "object", + "additionalProperties": { + "$ref": "#/definitions/multiformatMessageString" + } + }, + + "nestingLevel": { + "description": "An integer representing a containment hierarchy within the thread flow.", + "type": "integer", + "minimum": 0 + }, + + "executionOrder": { + "description": "An integer representing the temporal order in which execution reached this location.", + "type": "integer", + "default": -1, + "minimum": -1 + }, + + "executionTimeUtc": { + "description": "The Coordinated Universal Time (UTC) date and time at which this location was executed.", + "type": "string", + "format": "date-time" + }, + + "importance": { + "description": "Specifies the importance of this location in understanding the code flow in which it occurs. The order from most to least important is \"essential\", \"important\", \"unimportant\". Default: \"important\".", + "enum": ["important", "essential", "unimportant"], + "default": "important", + "type": "string" + }, + + "webRequest": { + "description": "A web request associated with this thread flow location.", + "$ref": "#/definitions/webRequest" + }, + + "webResponse": { + "description": "A web response associated with this thread flow location.", + "$ref": "#/definitions/webResponse" + }, + + "properties": { + "description": "Key/value pairs that provide additional information about the threadflow location.", + "$ref": "#/definitions/propertyBag" + } + } + }, + + "tool": { + "description": "The analysis tool that was run.", + "additionalProperties": false, + "type": "object", + "properties": { + "driver": { + "description": "The analysis tool that was run.", + "$ref": "#/definitions/toolComponent" + }, + + "extensions": { + "description": "Tool extensions that contributed to or reconfigured the analysis tool that was run.", + "type": "array", + "minItems": 0, + "uniqueItems": true, + "default": [], + "items": { + "$ref": "#/definitions/toolComponent" + } + }, + + "properties": { + "description": "Key/value pairs that provide additional information about the tool.", + "$ref": "#/definitions/propertyBag" + } + }, + + "required": ["driver"] + }, + + "toolComponent": { + "description": "A component, such as a plug-in or the driver, of the analysis tool that was run.", + "additionalProperties": false, + "type": "object", + "properties": { + "guid": { + "description": "A unique identifier for the tool component in the form of a GUID.", + "type": "string", + "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$" + }, + + "name": { + "description": "The name of the tool component.", + "type": "string" + }, + + "organization": { + "description": "The organization or company that produced the tool component.", + "type": "string" + }, + + "product": { + "description": "A product suite to which the tool component belongs.", + "type": "string" + }, + + "productSuite": { + "description": "A localizable string containing the name of the suite of products to which the tool component belongs.", + "type": "string" + }, + + "shortDescription": { + "description": "A brief description of the tool component.", + "$ref": "#/definitions/multiformatMessageString" + }, + + "fullDescription": { + "description": "A comprehensive description of the tool component.", + "$ref": "#/definitions/multiformatMessageString" + }, + + "fullName": { + "description": "The name of the tool component along with its version and any other useful identifying information, such as its locale.", + "type": "string" + }, + + "version": { + "description": "The tool component version, in whatever format the component natively provides.", + "type": "string" + }, + + "semanticVersion": { + "description": "The tool component version in the format specified by Semantic Versioning 2.0.", + "type": "string" + }, + + "dottedQuadFileVersion": { + "description": "The binary version of the tool component's primary executable file expressed as four non-negative integers separated by a period (for operating systems that express file versions in this way).", + "type": "string", + "pattern": "[0-9]+(\\.[0-9]+){3}" + }, + + "releaseDateUtc": { + "description": "A string specifying the UTC date (and optionally, the time) of the component's release.", + "type": "string" + }, + + "downloadUri": { + "description": "The absolute URI from which the tool component can be downloaded.", + "type": "string", + "format": "uri" + }, + + "informationUri": { + "description": "The absolute URI at which information about this version of the tool component can be found.", + "type": "string", + "format": "uri" + }, + + "globalMessageStrings": { + "description": "A dictionary, each of whose keys is a resource identifier and each of whose values is a multiformatMessageString object, which holds message strings in plain text and (optionally) Markdown format. The strings can include placeholders, which can be used to construct a message in combination with an arbitrary number of additional string arguments.", + "type": "object", + "additionalProperties": { + "$ref": "#/definitions/multiformatMessageString" + } + }, + + "notifications": { + "description": "An array of reportingDescriptor objects relevant to the notifications related to the configuration and runtime execution of the tool component.", + "type": "array", + "minItems": 0, + "uniqueItems": true, + "default": [], + "items": { + "$ref": "#/definitions/reportingDescriptor" + } + }, + + "rules": { + "description": "An array of reportingDescriptor objects relevant to the analysis performed by the tool component.", + "type": "array", + "minItems": 0, + "uniqueItems": true, + "default": [], + "items": { + "$ref": "#/definitions/reportingDescriptor" + } + }, + + "taxa": { + "description": "An array of reportingDescriptor objects relevant to the definitions of both standalone and tool-defined taxonomies.", + "type": "array", + "minItems": 0, + "uniqueItems": true, + "default": [], + "items": { + "$ref": "#/definitions/reportingDescriptor" + } + }, + + "locations": { + "description": "An array of the artifactLocation objects associated with the tool component.", + "type": "array", + "minItems": 0, + "default": [], + "items": { + "$ref": "#/definitions/artifactLocation" + } + }, + + "language": { + "description": "The language of the messages emitted into the log file during this run (expressed as an ISO 639-1 two-letter lowercase language code) and an optional region (expressed as an ISO 3166-1 two-letter uppercase subculture code associated with a country or region). The casing is recommended but not required (in order for this data to conform to RFC5646).", + "type": "string", + "default": "en-US", + "pattern": "^[a-zA-Z]{2}(-[a-zA-Z]{2})?$" + }, + + "contents": { + "description": "The kinds of data contained in this object.", + "type": "array", + "uniqueItems": true, + "default": ["localizedData", "nonLocalizedData"], + "items": { + "enum": ["localizedData", "nonLocalizedData"], + "type": "string" + } + }, + + "isComprehensive": { + "description": "Specifies whether this object contains a complete definition of the localizable and/or non-localizable data for this component, as opposed to including only data that is relevant to the results persisted to this log file.", + "type": "boolean", + "default": false + }, + + "localizedDataSemanticVersion": { + "description": "The semantic version of the localized strings defined in this component; maintained by components that provide translations.", + "type": "string" + }, + + "minimumRequiredLocalizedDataSemanticVersion": { + "description": "The minimum value of localizedDataSemanticVersion required in translations consumed by this component; used by components that consume translations.", + "type": "string" + }, + + "associatedComponent": { + "description": "The component which is strongly associated with this component. For a translation, this refers to the component which has been translated. For an extension, this is the driver that provides the extension's plugin model.", + "$ref": "#/definitions/toolComponentReference" + }, + + "translationMetadata": { + "description": "Translation metadata, required for a translation, not populated by other component types.", + "$ref": "#/definitions/translationMetadata" + }, + + "supportedTaxonomies": { + "description": "An array of toolComponentReference objects to declare the taxonomies supported by the tool component.", + "type": "array", + "minItems": 0, + "uniqueItems": true, + "default": [], + "items": { + "$ref": "#/definitions/toolComponentReference" + } + }, + + "properties": { + "description": "Key/value pairs that provide additional information about the tool component.", + "$ref": "#/definitions/propertyBag" + } + }, + + "required": ["name"] + }, + + "toolComponentReference": { + "description": "Identifies a particular toolComponent object, either the driver or an extension.", + "type": "object", + "additionalProperties": false, + "properties": { + "name": { + "description": "The 'name' property of the referenced toolComponent.", + "type": "string" + }, + + "index": { + "description": "An index into the referenced toolComponent in tool.extensions.", + "type": "integer", + "default": -1, + "minimum": -1 + }, + + "guid": { + "description": "The 'guid' property of the referenced toolComponent.", + "type": "string", + "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$" + }, + + "properties": { + "description": "Key/value pairs that provide additional information about the toolComponentReference.", + "$ref": "#/definitions/propertyBag" + } + } + }, + + "translationMetadata": { + "description": "Provides additional metadata related to translation.", + "type": "object", + "additionalProperties": false, + "properties": { + "name": { + "description": "The name associated with the translation metadata.", + "type": "string" + }, + + "fullName": { + "description": "The full name associated with the translation metadata.", + "type": "string" + }, + + "shortDescription": { + "description": "A brief description of the translation metadata.", + "$ref": "#/definitions/multiformatMessageString" + }, + + "fullDescription": { + "description": "A comprehensive description of the translation metadata.", + "$ref": "#/definitions/multiformatMessageString" + }, + + "downloadUri": { + "description": "The absolute URI from which the translation metadata can be downloaded.", + "type": "string", + "format": "uri" + }, + + "informationUri": { + "description": "The absolute URI from which information related to the translation metadata can be downloaded.", + "type": "string", + "format": "uri" + }, + + "properties": { + "description": "Key/value pairs that provide additional information about the translation metadata.", + "$ref": "#/definitions/propertyBag" + } + }, + "required": ["name"] + }, + + "versionControlDetails": { + "description": "Specifies the information necessary to retrieve a desired revision from a version control system.", + "type": "object", + "additionalProperties": false, + "properties": { + "repositoryUri": { + "description": "The absolute URI of the repository.", + "type": "string", + "format": "uri" + }, + + "revisionId": { + "description": "A string that uniquely and permanently identifies the revision within the repository.", + "type": "string" + }, + + "branch": { + "description": "The name of a branch containing the revision.", + "type": "string" + }, + + "revisionTag": { + "description": "A tag that has been applied to the revision.", + "type": "string" + }, + + "asOfTimeUtc": { + "description": "A Coordinated Universal Time (UTC) date and time that can be used to synchronize an enlistment to the state of the repository at that time.", + "type": "string", + "format": "date-time" + }, + + "mappedTo": { + "description": "The location in the local file system to which the root of the repository was mapped at the time of the analysis.", + "$ref": "#/definitions/artifactLocation" + }, + + "properties": { + "description": "Key/value pairs that provide additional information about the version control details.", + "$ref": "#/definitions/propertyBag" + } + }, + + "required": ["repositoryUri"] + }, + + "webRequest": { + "description": "Describes an HTTP request.", + "type": "object", + "additionalProperties": false, + "properties": { + "index": { + "description": "The index within the run.webRequests array of the request object associated with this result.", + "type": "integer", + "default": -1, + "minimum": -1 + }, + + "protocol": { + "description": "The request protocol. Example: 'http'.", + "type": "string" + }, + + "version": { + "description": "The request version. Example: '1.1'.", + "type": "string" + }, + + "target": { + "description": "The target of the request.", + "type": "string" + }, + + "method": { + "description": "The HTTP method. Well-known values are 'GET', 'PUT', 'POST', 'DELETE', 'PATCH', 'HEAD', 'OPTIONS', 'TRACE', 'CONNECT'.", + "type": "string" + }, + + "headers": { + "description": "The request headers.", + "type": "object", + "additionalProperties": { + "type": "string" + } + }, + + "parameters": { + "description": "The request parameters.", + "type": "object", + "additionalProperties": { + "type": "string" + } + }, + + "body": { + "description": "The body of the request.", + "$ref": "#/definitions/artifactContent" + }, + + "properties": { + "description": "Key/value pairs that provide additional information about the request.", + "$ref": "#/definitions/propertyBag" + } + } + }, + + "webResponse": { + "description": "Describes the response to an HTTP request.", + "type": "object", + "additionalProperties": false, + "properties": { + "index": { + "description": "The index within the run.webResponses array of the response object associated with this result.", + "type": "integer", + "default": -1, + "minimum": -1 + }, + + "protocol": { + "description": "The response protocol. Example: 'http'.", + "type": "string" + }, + + "version": { + "description": "The response version. Example: '1.1'.", + "type": "string" + }, + + "statusCode": { + "description": "The response status code. Example: 451.", + "type": "integer" + }, + + "reasonPhrase": { + "description": "The response reason. Example: 'Not found'.", + "type": "string" + }, + + "headers": { + "description": "The response headers.", + "type": "object", + "additionalProperties": { + "type": "string" + } + }, + + "body": { + "description": "The body of the response.", + "$ref": "#/definitions/artifactContent" + }, + + "noResponseReceived": { + "description": "Specifies whether a response was received from the server.", + "type": "boolean", + "default": false + }, + + "properties": { + "description": "Key/value pairs that provide additional information about the response.", + "$ref": "#/definitions/propertyBag" + } + } + } + } +} diff --git a/orchestrator/docs/api/sarif-schema.json b/orchestrator/docs/api/sarif-schema.json index cb03c979..56860a0e 100644 --- a/orchestrator/docs/api/sarif-schema.json +++ b/orchestrator/docs/api/sarif-schema.json @@ -1,8 +1,8 @@ { "$schema": "http://json-schema.org/draft-04/schema#", - "title": "AIXCC Enhanced Static Analysis Results Format (SARIF) Version 2.1.0 JSON Schema", - "id": "https://aixcc.tech/sarif-schema-v0.3.json", - "description": "AIXCC Enhanced Static Analysis Results Format (SARIF) Version 2.1.0 JSON Schema: a standard format for the output of static analysis tools.", + "title": "Static Analysis Results Format (SARIF) Version 2.1.0 JSON Schema", + "id": "https://docs.oasis-open.org/sarif/sarif/v2.1.0/errata01/os/schemas/sarif-schema-2.1.0.json", + "description": "Static Analysis Results Format (SARIF) Version 2.1.0 JSON Schema: a standard format for the output of static analysis tools.", "additionalProperties": false, "type": "object", "properties": { @@ -2233,7 +2233,7 @@ "$ref": "#/definitions/propertyBag" } }, - "required": ["message", "ruleId"] + "required": ["message"] }, "resultProvenance": { diff --git a/orchestrator/docs/tailscale-hosted-competitor-test-server/hosted_competitor_test_server.md b/orchestrator/docs/tailscale-hosted-competitor-test-server/hosted_competitor_test_server.md new file mode 100644 index 00000000..9751fd13 --- /dev/null +++ b/orchestrator/docs/tailscale-hosted-competitor-test-server/hosted_competitor_test_server.md @@ -0,0 +1,68 @@ +# Tailnet-accessible hosted Competitor Test Server + +The organizers have set up a test competition API server for each team that is reachable from the internet, but tasks your CRS hosted on the tailnet. Telemetry from these runs get forwarded to your team’s telemetry +server. + +It is intended that competitors may use this to task their CRS with challenges from prior rounds that are available in the aixcc-finals org. There are three changes to your CRS deployment that are required in order for +you to use this server. + +1. Change the URL of the Competition API to `https://test--api.tail7e9b4c.ts.net` +2. If you are using Kubernetes Tailscale Operator, add another Service for this test URL so that it can be accessible from your cluster. See + [proxies.yaml](https://github.com/aixcc-finals/example-crs-architecture/blob/main/example-crs-architecture/k8s/base/tailscale-connections/proxies.yaml) for context. +3. Append `-testing` to your CRS hostname, for example `team-moniker-testing`. This is the URL that is configured by default. + +If you want to use a different CRS URL **for the tailscale-hosted competitor test server**, use the following: + +Update CRS hostname used by the hosted competitor testing server + +```bash +curl -u 11111111-1111-1111-1111-111111111111:pY8rLk7FvQ2hZm9GwUx3Ej5BnTcV4So0 -X PATCH https://.tasker.aixcc.tech/crs/url/ -H 'Content-Type: application/json' -d '{"hostname":"team-moniker-testing-1"}' +``` + +Get CRS hostname used by the hosted competitor testing server + +```bash +curl -u 11111111-1111-1111-1111-111111111111:pY8rLk7FvQ2hZm9GwUx3Ej5BnTcV4So0 https://.tasker.aixcc.tech/crs/url/ +``` + +Kick off tasks with the server + +```bash +# Integration Test +curl -u 11111111-1111-1111-1111-111111111111:pY8rLk7FvQ2hZm9GwUx3Ej5BnTcV4So0 -X 'POST' 'https://.tasker.aixcc.tech/v1/request/delta/' +# LibPNG +curl -u 11111111-1111-1111-1111-111111111111:pY8rLk7FvQ2hZm9GwUx3Ej5BnTcV4So0 -X 'POST' 'https://.tasker.aixcc.tech/webhook/trigger_task' -H 'Content-Type: application/json' -d '{ + "challenge_repo_url": "git@github.com:aixcc-finals/example-libpng.git", + "challenge_repo_base_ref": "0cc367aaeaac3f888f255cee5d394968996f736e", + "challenge_repo_head_ref": "fdacd5a1dcff42175117d674b0fda9f8a005ae88", + "fuzz_tooling_url": "https://github.com/aixcc-finals/oss-fuzz-aixcc.git", + "fuzz_tooling_ref": "d5fbd68fca66e6fa4f05899170d24e572b01853d", + "fuzz_tooling_project_name": "libpng", + "duration": 3600 +}' +# Zookeeper +curl -u 11111111-1111-1111-1111-111111111111:pY8rLk7FvQ2hZm9GwUx3Ej5BnTcV4So0 -X 'POST' 'https://.tasker.aixcc.tech/webhook/trigger_task' -H 'Content-Type: application/json' -d '{ + "challenge_repo_url": "git@github.com:aixcc-finals/afc-zookeeper.git", + "challenge_repo_base_ref": "d19cef9ca254a4c1461490ed8b82ffccfa57461d", + "challenge_repo_head_ref": "5ee4f185d0431cc88f365ce779aa04a87fe7690f", + "fuzz_tooling_url": "https://github.com/aixcc-finals/oss-fuzz-aixcc.git", + "fuzz_tooling_ref": "challenge-state/zk-ex1-delta-01", + "fuzz_tooling_project_name": "zookeeper", + "duration": 3600 +}' +# Libxml2 +curl -u 11111111-1111-1111-1111-111111111111:pY8rLk7FvQ2hZm9GwUx3Ej5BnTcV4So0 -X 'POST' 'https://.tasker.aixcc.tech/webhook/trigger_task' -H 'Content-Type: application/json' -d '{ + "challenge_repo_url": "git@github.com:aixcc-finals/afc-libxml2.git", + "challenge_repo_base_ref": "792cc4a1462d4a969d9d38bd80a52d2e4f7bd137", + "challenge_repo_head_ref": "9d1cb67c31933ee5ae3ee458940f7dbeb2fde8b8", + "fuzz_tooling_url": "https://github.com/aixcc-finals/oss-fuzz-aixcc.git", + "fuzz_tooling_ref": "challenge-state/lx-ex1-delta-01", + "fuzz_tooling_project_name": "libxml2", + "duration": 3600 +}' + +``` + +## IMPORTANT NOTE + +If you are using this test server, don’t forget to change your Competition API URL back to `https://api.tail7e9b4c.ts.net` prior to the start of the round. diff --git a/orchestrator/docs/tailscale-hosted-competitor-test-server/tailscale_management_tools.md b/orchestrator/docs/tailscale-hosted-competitor-test-server/tailscale_management_tools.md new file mode 100644 index 00000000..fb3c48aa --- /dev/null +++ b/orchestrator/docs/tailscale-hosted-competitor-test-server/tailscale_management_tools.md @@ -0,0 +1,44 @@ +# Tailscale Management Tools + +Each team has access to a set of APIs to manage their Tailscale devices. You can use this tool to list devices, delete devices, and update hostnames of tailscale devices. Each endpoint uses the Competition API +credentials for your team. + +List Devices + +Lists devices on the tailnet for your team. + +```bash +curl -u 11111111-1111-1111-1111-111111111111:pY8rLk7FvQ2hZm9GwUx3Ej5BnTcV4So0 https://.tasker.aixcc.tech/tailscale/device/ +``` + +Show Device + +Shows information about a single device by name + +```bash +curl -u 11111111-1111-1111-1111-111111111111:pY8rLk7FvQ2hZm9GwUx3Ej5BnTcV4So0 https://.tasker.aixcc.tech/tailscale/device/team-moniker-foo +``` + +Rename Device + +Change the hostname of a device on the tailnet + +```bash +curl -u 11111111-1111-1111-1111-111111111111:pY8rLk7FvQ2hZm9GwUx3Ej5BnTcV4So0 -X PATCH https://.tasker.aixcc.tech/tailscale/device/team-moniker-foo -H 'Content-Type: application/json' -d '{"hostname":"team-moniker-exhibition2"}' +``` + +Delete Device + +Deletes a specific device on the tailnet + +```bash +curl -u 11111111-1111-1111-1111-111111111111:pY8rLk7FvQ2hZm9GwUx3Ej5BnTcV4So0 -X DELETE https://.tasker.aixcc.tech/tailscale/device/team-moniker-foo +``` + +Delete all Devices + +**WARNING** This deletes all devices on your team’s tailnet. + +```bash +curl -u 11111111-1111-1111-1111-111111111111:pY8rLk7FvQ2hZm9GwUx3Ej5BnTcV4So0 -X DELETE https://.tasker.aixcc.tech/tailscale/device/ +``` diff --git a/orchestrator/docs/telemetry/README.md b/orchestrator/docs/telemetry/README.md index 4572aaea..06b9d06b 100644 --- a/orchestrator/docs/telemetry/README.md +++ b/orchestrator/docs/telemetry/README.md @@ -1,5 +1,7 @@ # CRS Telemetry Specification v1.0 +For Telemetry Best Practices, see [here](telemetry_best_practices.md) + Telemetry generated by a CRS is submitted in two distinct ways: 1. GenAI (LLM requests and responses) diff --git a/orchestrator/docs/telemetry/telemetry_best_practices.md b/orchestrator/docs/telemetry/telemetry_best_practices.md new file mode 100644 index 00000000..45a7478e --- /dev/null +++ b/orchestrator/docs/telemetry/telemetry_best_practices.md @@ -0,0 +1,29 @@ +# General telemetry guidance + +1. All work performed on challenges should be described by spans, and these spans must specify `round.id`, `task.id`, `crs.action.category` and `crs.action.name` (teams are free to choose their own names for + crs.action.name, but it should be descriptive of the kind of work being performed) +1. Spans/Traces should not be used for general-purpose logging. Use OpenTelemetry Logs for this purpose. +1. All LLM requests' telemetry must be linked to a parent span that describes a unit of work that the LLM request contributes towards. + +## Improving the structure of OTEL data + +1. A trace is made up of spans that share a `trace_id` , and a trace must describe a distinct non-trivial effort that is mapped to a single `task.id`. Said differently: a trace should not span across multiple tasks, but + a single task may have multiple traces. + 1. A trace may have one or more “root spans” (a span with no `parent_span_id`), but a single root span per trace is preferred. + 1. A trace should encompass a non-trivial number of spans. A small number of spans in a trace should indicate unusual or exceptional behavior. +1. Spans must be linked to indicate relationships between spans either via parent/child relationships or via span links + 1. A parent/child relationship indicated by `parent_span_id` is expected for all units of work that are nested under a larger unit of work (e.g. function calls under an API endpoint, or LLM queries to service an + asynchronous task). + 1. In cases where a multiple spans contribute to a new unit of work, or spans have a causal relationship (asynchronous, sequential, etc), span `links` must be used instead of parent/child relationships. + 1. In order for the telemetry data to be meaningful, the links between spans must reflect the order and hierarchy of work performed. This means that span relationships should generally form tree-like graphs rather + than unlinked spans. Accomplishing this may require adding a telemetry span at a higher logical level in order to properly describe the hierarchy of work performed. + +## Verifying telemetry + +On your team's SigNoz server, you may check for the following attributes: `crs.action.category`, `round.id`, `task.id`, & `gen_ai.request.model` as a general means to verify the requested telemetry is being provided. + +These attributes provide the following: + +- `crs.action.category` attribute confirms CRS telemetry spans were sent +- `round.id/task.id` are examples of attributes from a Task's `metadata` field. These need to be supplied in the spans. (confirms correct task metadata field passthrough) +- `gen_ai.request.model` attribute existing confirms LLM telemetry diff --git a/orchestrator/pyproject.toml b/orchestrator/pyproject.toml index 7abb40fb..c901a63c 100644 --- a/orchestrator/pyproject.toml +++ b/orchestrator/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "orchestrator" -version = "0.1.3" +version = "0.1.4" description = "Buttercup orchestrator" readme = "README.md" authors = [{ name = "Trail of Bits", email = "opensource@trailofbits.com" }] diff --git a/orchestrator/src/buttercup/orchestrator/.openapi-generator/VERSION b/orchestrator/src/buttercup/orchestrator/.openapi-generator/VERSION index 96cfbb19..4c631cf2 100644 --- a/orchestrator/src/buttercup/orchestrator/.openapi-generator/VERSION +++ b/orchestrator/src/buttercup/orchestrator/.openapi-generator/VERSION @@ -1 +1 @@ -7.13.0-SNAPSHOT +7.14.0-SNAPSHOT diff --git a/orchestrator/src/buttercup/orchestrator/competition_api_client/models/types_architecture.py b/orchestrator/src/buttercup/orchestrator/competition_api_client/models/types_architecture.py index f081eac1..d7eae78f 100644 --- a/orchestrator/src/buttercup/orchestrator/competition_api_client/models/types_architecture.py +++ b/orchestrator/src/buttercup/orchestrator/competition_api_client/models/types_architecture.py @@ -26,7 +26,7 @@ class TypesArchitecture(str, Enum): """ allowed enum values """ - X86_64 = 'x86_64' + ArchitectureX8664 = 'x86_64' @classmethod def from_json(cls, json_str: str) -> Self: diff --git a/orchestrator/src/buttercup/orchestrator/competition_api_client/models/types_assessment.py b/orchestrator/src/buttercup/orchestrator/competition_api_client/models/types_assessment.py index 42955a26..cb218177 100644 --- a/orchestrator/src/buttercup/orchestrator/competition_api_client/models/types_assessment.py +++ b/orchestrator/src/buttercup/orchestrator/competition_api_client/models/types_assessment.py @@ -26,8 +26,8 @@ class TypesAssessment(str, Enum): """ allowed enum values """ - CORRECT = 'correct' - INCORRECT = 'incorrect' + AssessmentCorrect = 'correct' + AssessmentIncorrect = 'incorrect' @classmethod def from_json(cls, json_str: str) -> Self: diff --git a/orchestrator/src/buttercup/orchestrator/competition_api_client/models/types_submission_status.py b/orchestrator/src/buttercup/orchestrator/competition_api_client/models/types_submission_status.py index b4646173..5413f88a 100644 --- a/orchestrator/src/buttercup/orchestrator/competition_api_client/models/types_submission_status.py +++ b/orchestrator/src/buttercup/orchestrator/competition_api_client/models/types_submission_status.py @@ -26,11 +26,11 @@ class TypesSubmissionStatus(str, Enum): """ allowed enum values """ - ACCEPTED = 'accepted' - PASSED = 'passed' - FAILED = 'failed' - DEADLINE_EXCEEDED = 'deadline_exceeded' - ERRORED = 'errored' + SubmissionStatusAccepted = 'accepted' + SubmissionStatusPassed = 'passed' + SubmissionStatusFailed = 'failed' + SubmissionStatusDeadlineExceeded = 'deadline_exceeded' + SubmissionStatusErrored = 'errored' @classmethod def from_json(cls, json_str: str) -> Self: diff --git a/orchestrator/src/buttercup/orchestrator/scheduler/submissions.py b/orchestrator/src/buttercup/orchestrator/scheduler/submissions.py index e8dade9d..2d354f73 100644 --- a/orchestrator/src/buttercup/orchestrator/scheduler/submissions.py +++ b/orchestrator/src/buttercup/orchestrator/scheduler/submissions.py @@ -14,12 +14,12 @@ from buttercup.common.datastructures.msg_pb2 import ( Patch, ) from buttercup.common.sarif_store import SARIFStore -from buttercup.common.constants import ARCHITECTURE from buttercup.common.queues import QueueFactory, QueueNames from buttercup.common.telemetry import set_crs_attributes, CRSActionCategory from buttercup.orchestrator.scheduler.sarif_matcher import match from buttercup.orchestrator.registry import TaskRegistry +from buttercup.orchestrator.competition_api_client.models.types_architecture import TypesArchitecture from buttercup.orchestrator.competition_api_client.models.types_pov_submission import TypesPOVSubmission from buttercup.orchestrator.competition_api_client.models.types_patch_submission import TypesPatchSubmission from buttercup.orchestrator.competition_api_client.models.types_bundle_submission import TypesBundleSubmission @@ -142,7 +142,7 @@ class CompetitionAPI: # Create submission payload from crash data submission = TypesPOVSubmission( - architecture=ARCHITECTURE, + architecture=TypesArchitecture.ArchitectureX8664, engine=crash.crash.target.engine, fuzzer_name=crash.crash.harness_name, sanitizer=crash.crash.target.sanitizer, @@ -168,7 +168,10 @@ class CompetitionAPI: payload=submission, ) logger.debug(f"[{crash.crash.target.task_id}] POV submission response: {response}") - if response.status not in [TypesSubmissionStatus.ACCEPTED, TypesSubmissionStatus.PASSED]: + if response.status not in [ + TypesSubmissionStatus.SubmissionStatusAccepted, + TypesSubmissionStatus.SubmissionStatusPassed, + ]: logger.error( f"[{crash.crash.target.task_id}] POV submission rejected (status: {response.status}) for harness: {crash.crash.harness_name}" ) @@ -179,7 +182,7 @@ class CompetitionAPI: return response.pov_id, response.status except Exception as e: logger.error(f"[{crash.crash.target.task_id}] Failed to submit vulnerability: {e}") - return None, TypesSubmissionStatus.ERRORED + return None, TypesSubmissionStatus.SubmissionStatusErrored def get_pov_status(self, task_id: str, pov_id: str) -> TypesSubmissionStatus: """ @@ -190,7 +193,7 @@ class CompetitionAPI: pov_id: POV ID from submit_vulnerability Returns: - TypesSubmissionStatus: Current status (ACCEPTED, PASSED, FAILED, ERRORED, DEADLINE_EXCEEDED) + TypesSubmissionStatus: Current status (SubmissionStatusAccepted, SubmissionStatusPassed, SubmissionStatusFailed, SubmissionStatusErrored, SubmissionStatusDeadlineExceeded) """ assert task_id assert pov_id @@ -232,7 +235,10 @@ class CompetitionAPI: task_id=task_id, payload=submission ) logger.debug(f"[{task_id}] Patch submission response: {response}") - if response.status not in [TypesSubmissionStatus.ACCEPTED, TypesSubmissionStatus.PASSED]: + if response.status not in [ + TypesSubmissionStatus.SubmissionStatusAccepted, + TypesSubmissionStatus.SubmissionStatusPassed, + ]: logger.error(f"[{task_id}] Patch submission rejected (status: {response.status}) for harness: {patch}") span.set_status(Status(StatusCode.ERROR)) return (None, response.status) @@ -249,7 +255,7 @@ class CompetitionAPI: patch_id: Patch ID from submit_patch Returns: - TypesSubmissionStatus: Current status (ACCEPTED, PASSED, FAILED, ERRORED, DEADLINE_EXCEEDED) + TypesSubmissionStatus: Current status (SubmissionStatusAccepted, SubmissionStatusPassed, SubmissionStatusFailed, SubmissionStatusErrored, SubmissionStatusDeadlineExceeded) """ assert task_id assert patch_id @@ -300,7 +306,10 @@ class CompetitionAPI: task_id=task_id, payload=submission ) logger.debug(f"[{task_id}] Bundle submission response: {response}") - if response.status not in [TypesSubmissionStatus.ACCEPTED, TypesSubmissionStatus.PASSED]: + if response.status not in [ + TypesSubmissionStatus.SubmissionStatusAccepted, + TypesSubmissionStatus.SubmissionStatusPassed, + ]: logger.error( f"[{task_id}] Bundle submission rejected (status: {response.status}) for harness: {pov_id} {patch_id}" ) @@ -344,7 +353,10 @@ class CompetitionAPI: task_id=task_id, bundle_id=bundle_id, payload=submission ) logger.debug(f"[{task_id}] Bundle patch submission response: {response}") - if response.status not in [TypesSubmissionStatus.ACCEPTED, TypesSubmissionStatus.PASSED]: + if response.status not in [ + TypesSubmissionStatus.SubmissionStatusAccepted, + TypesSubmissionStatus.SubmissionStatusPassed, + ]: logger.error( f"[{task_id}] Bundle patch submission rejected (status: {response.status}) for harness: {pov_id} {patch_id} {sarif_id}" ) @@ -371,7 +383,7 @@ class CompetitionAPI: # TODO: The description is the most basic I could think of. I don't know if we wanted to do something more fancy. submission = TypesSarifAssessmentSubmission( - assessment=TypesAssessment.CORRECT, + assessment=TypesAssessment.AssessmentCorrect, description="Overlapping with our POV/patch", ) @@ -391,7 +403,10 @@ class CompetitionAPI: task_id=task_id, broadcast_sarif_id=sarif_id, payload=submission ) logger.debug(f"[{task_id}] Matching SARIF submission response: {response}") - if response.status not in [TypesSubmissionStatus.ACCEPTED, TypesSubmissionStatus.PASSED]: + if response.status not in [ + TypesSubmissionStatus.SubmissionStatusAccepted, + TypesSubmissionStatus.SubmissionStatusPassed, + ]: logger.error( f"[{task_id}] Matching SARIF submission rejected (status: {response.status}) for sarif_id: {sarif_id}" ) @@ -594,7 +609,7 @@ class Submissions: ) # If the API returned ERRORED, we want to retry. - stop = status != TypesSubmissionStatus.ERRORED + stop = status != TypesSubmissionStatus.SubmissionStatusErrored if stop: logger.info(f"Competition API returned {status}, will not retry.") @@ -696,7 +711,7 @@ class Submissions: """ status = self.competition_api.get_pov_status(_task_id(e), e.pov_id) match status: - case TypesSubmissionStatus.FAILED | TypesSubmissionStatus.DEADLINE_EXCEEDED: + case TypesSubmissionStatus.SubmissionStatusFailed | TypesSubmissionStatus.SubmissionStatusDeadlineExceeded: e.state = SubmissionEntry.STOP self._persist(self.redis, i, e) log_structured( @@ -707,7 +722,7 @@ class Submissions: state_change=("WAIT_POV_PASS", "STOP"), msg=f"POV failed (status={status}), stopping", ) - case TypesSubmissionStatus.PASSED: + case TypesSubmissionStatus.SubmissionStatusPassed: e.state = SubmissionEntry.SUBMIT_PATCH self._persist(self.redis, i, e) log_structured( @@ -718,7 +733,7 @@ class Submissions: state_change=("WAIT_POV_PASS", "SUBMIT_PATCH"), msg="POV passed, ready to submit patch when the patch is ready", ) - case TypesSubmissionStatus.ERRORED: + case TypesSubmissionStatus.SubmissionStatusErrored: log_structured(logger.info, _task_id(e), index=i, pov_id=e.pov_id, msg="POV errored, will resubmit") pov_id, status = self.competition_api.submit_pov(e.crash) @@ -730,7 +745,7 @@ class Submissions: ) # If the API returned ERRORED, we want to retry. - if status != TypesSubmissionStatus.ERRORED: + if status != TypesSubmissionStatus.SubmissionStatusErrored: e.state = SubmissionEntry.STOP self._persist(self.redis, i, e) log_structured( @@ -749,7 +764,7 @@ class Submissions: ) case _: - assert status == TypesSubmissionStatus.ACCEPTED, f"Unexpected POV status: {status}" + assert status == TypesSubmissionStatus.SubmissionStatusAccepted, f"Unexpected POV status: {status}" def _submit_patch(self, i, e): """ @@ -794,7 +809,10 @@ class Submissions: ) else: match status: - case TypesSubmissionStatus.FAILED | TypesSubmissionStatus.DEADLINE_EXCEEDED: + case ( + TypesSubmissionStatus.SubmissionStatusFailed + | TypesSubmissionStatus.SubmissionStatusDeadlineExceeded + ): # Deadline exceeded or failed, move on to next patch (for exceeded we won't try again due to deadline check) e.patch_idx += 1 self._persist(self.redis, i, e) @@ -806,7 +824,7 @@ class Submissions: patch_idx=e.patch_idx, msg=f"Patch submission failed ({status}), will not attempt this patch again.", ) - case TypesSubmissionStatus.ERRORED: + case TypesSubmissionStatus.SubmissionStatusErrored: if have_more_patches and e.patch_submission_attempt >= self.patch_submission_retry_limit: _advance_patch_idx(e) self._persist(self.redis, i, e) @@ -847,9 +865,9 @@ class Submissions: """ status = self.competition_api.get_patch_status(_task_id(e), e.patch_id) match status: - case TypesSubmissionStatus.ACCEPTED: + case TypesSubmissionStatus.SubmissionStatusAccepted: return # No change. - case TypesSubmissionStatus.FAILED | TypesSubmissionStatus.DEADLINE_EXCEEDED: + case TypesSubmissionStatus.SubmissionStatusFailed | TypesSubmissionStatus.SubmissionStatusDeadlineExceeded: _advance_patch_idx(e) e.state = SubmissionEntry.SUBMIT_PATCH self._persist(self.redis, i, e) @@ -862,7 +880,7 @@ class Submissions: state_change=("WAIT_PATCH_PASS", "SUBMIT_PATCH"), msg=f"Patch submission failed ({status}), will not attempt this patch again, moving on to next patch.", ) - case TypesSubmissionStatus.ERRORED: + case TypesSubmissionStatus.SubmissionStatusErrored: e.state = SubmissionEntry.SUBMIT_PATCH self._persist(self.redis, i, e) log_structured( @@ -874,7 +892,7 @@ class Submissions: state_change=("WAIT_PATCH_PASS", "SUBMIT_PATCH"), msg=f"Patch submission errored ({status}), will attempt this patch again.", ) - case TypesSubmissionStatus.PASSED: + case TypesSubmissionStatus.SubmissionStatusPassed: e.state = SubmissionEntry.SUBMIT_BUNDLE self._persist(self.redis, i, e) log_structured( @@ -904,7 +922,10 @@ class Submissions: bundle_id, status = self.competition_api.submit_bundle(_task_id(e), e.pov_id, e.patch_id) if not bundle_id: match status: - case TypesSubmissionStatus.FAILED | TypesSubmissionStatus.DEADLINE_EXCEEDED: + case ( + TypesSubmissionStatus.SubmissionStatusFailed + | TypesSubmissionStatus.SubmissionStatusDeadlineExceeded + ): e.state = SubmissionEntry.STOP self._persist(self.redis, i, e) log_structured( @@ -916,7 +937,7 @@ class Submissions: state_change=("SUBMIT_BUNDLE", "STOP"), msg=f"Bundle submission failed ({status}), not much else to do but stop.", ) - case TypesSubmissionStatus.ERRORED: + case TypesSubmissionStatus.SubmissionStatusErrored: log_structured( logger.info, _task_id(e), @@ -1002,7 +1023,10 @@ class Submissions: ) else: match status: - case TypesSubmissionStatus.FAILED | TypesSubmissionStatus.DEADLINE_EXCEEDED: + case ( + TypesSubmissionStatus.SubmissionStatusFailed + | TypesSubmissionStatus.SubmissionStatusDeadlineExceeded + ): e.state = SubmissionEntry.STOP self._persist(self.redis, i, e) log_structured( @@ -1056,7 +1080,10 @@ class Submissions: ) else: match status: - case TypesSubmissionStatus.FAILED | TypesSubmissionStatus.DEADLINE_EXCEEDED: + case ( + TypesSubmissionStatus.SubmissionStatusFailed + | TypesSubmissionStatus.SubmissionStatusDeadlineExceeded + ): e.state = SubmissionEntry.STOP self._persist(self.redis, i, e) log_structured( diff --git a/orchestrator/src/buttercup/orchestrator/task_server/models/__init__.py b/orchestrator/src/buttercup/orchestrator/task_server/models/__init__.py index b135ce0b..0574f083 100644 --- a/orchestrator/src/buttercup/orchestrator/task_server/models/__init__.py +++ b/orchestrator/src/buttercup/orchestrator/task_server/models/__init__.py @@ -1,3 +1,3 @@ # generated by fastapi-codegen: -# filename: /tmp/tmp.4yUHNSUOxp/openapi.json -# timestamp: 2025-03-19T10:11:57+00:00 +# filename: /tmp/tmp.0oVFmuzKjt/openapi.json +# timestamp: 2025-05-02T05:12:50+00:00 diff --git a/orchestrator/src/buttercup/orchestrator/task_server/models/types.py b/orchestrator/src/buttercup/orchestrator/task_server/models/types.py index 51cb9a7e..fc23475c 100644 --- a/orchestrator/src/buttercup/orchestrator/task_server/models/types.py +++ b/orchestrator/src/buttercup/orchestrator/task_server/models/types.py @@ -1,6 +1,6 @@ # generated by fastapi-codegen: -# filename: /tmp/tmp.4yUHNSUOxp/openapi.json -# timestamp: 2025-03-19T10:11:57+00:00 +# filename: /tmp/tmp.0oVFmuzKjt/openapi.json +# timestamp: 2025-05-02T05:12:50+00:00 from __future__ import annotations diff --git a/orchestrator/src/buttercup/orchestrator/task_server/server.py b/orchestrator/src/buttercup/orchestrator/task_server/server.py index c72bb72b..40cd46b6 100644 --- a/orchestrator/src/buttercup/orchestrator/task_server/server.py +++ b/orchestrator/src/buttercup/orchestrator/task_server/server.py @@ -1,6 +1,6 @@ # generated by fastapi-codegen: # filename: openapi.json -# timestamp: 2025-02-18T14:23:33+00:00 +# timestamp: 2025-05-02T05:12:50+00:00 from __future__ import annotations diff --git a/orchestrator/test/test_submissions.py b/orchestrator/test/test_submissions.py index 6d27a140..15cb986c 100644 --- a/orchestrator/test/test_submissions.py +++ b/orchestrator/test/test_submissions.py @@ -83,7 +83,7 @@ def mock_redis(): def mock_competition_api(mock_task_registry): mock = Mock(spec=CompetitionAPI) # Add the missing method that's needed in tests - mock.submit_bundle_patch = Mock(return_value=(True, TypesSubmissionStatus.ACCEPTED)) + mock.submit_bundle_patch = Mock(return_value=(True, TypesSubmissionStatus.SubmissionStatusAccepted)) return mock @@ -122,7 +122,9 @@ class TestCompetitionAPI: mock_lopen.return_value.__enter__.return_value = mock_file # Setup API response - mock_response = TypesPOVSubmissionResponse(status=TypesSubmissionStatus.ACCEPTED, pov_id="test-pov-123") + mock_response = TypesPOVSubmissionResponse( + status=TypesSubmissionStatus.SubmissionStatusAccepted, pov_id="test-pov-123" + ) # Setup API client mock mock_pov_api = Mock() @@ -135,7 +137,7 @@ class TestCompetitionAPI: # Verify result first assert result[0] == "test-pov-123" - assert result[1] == TypesSubmissionStatus.ACCEPTED + assert result[1] == TypesSubmissionStatus.SubmissionStatusAccepted # Verify file was read correctly mock_lopen.assert_called_once_with(sample_crash.crash.crash_input_path, "rb") @@ -160,7 +162,7 @@ class TestCompetitionAPI: mock_lopen.return_value.__enter__.return_value = mock_file # Setup API response - mock_response = TypesPOVSubmissionResponse(status=TypesSubmissionStatus.FAILED, pov_id="") + mock_response = TypesPOVSubmissionResponse(status=TypesSubmissionStatus.SubmissionStatusFailed, pov_id="") # Setup API client mock mock_pov_api = Mock() @@ -173,12 +175,14 @@ class TestCompetitionAPI: # Verify result is a tuple with (None, FAILED) assert result[0] is None - assert result[1] == TypesSubmissionStatus.FAILED + assert result[1] == TypesSubmissionStatus.SubmissionStatusFailed def test_get_pov_status(self, competition_api): # Setup mock mock_pov_api = Mock() - mock_pov_api.v1_task_task_id_pov_pov_id_get.return_value = Mock(status=TypesSubmissionStatus.PASSED) + mock_pov_api.v1_task_task_id_pov_pov_id_get.return_value = Mock( + status=TypesSubmissionStatus.SubmissionStatusPassed + ) # Patch the PovApi constructor with patch("buttercup.orchestrator.scheduler.submissions.PovApi", return_value=mock_pov_api): @@ -187,7 +191,7 @@ class TestCompetitionAPI: # Verify call and result mock_pov_api.v1_task_task_id_pov_pov_id_get.assert_called_once_with(task_id="task-123", pov_id="pov-456") - assert status == TypesSubmissionStatus.PASSED + assert status == TypesSubmissionStatus.SubmissionStatusPassed def test_submit_patch_successful(self, competition_api): # Setup test data @@ -196,7 +200,9 @@ class TestCompetitionAPI: expected_encoded_patch = base64.b64encode(patch_content.encode()).decode() # Setup mock response - mock_response = TypesPatchSubmissionResponse(status=TypesSubmissionStatus.ACCEPTED, patch_id="patch-123") + mock_response = TypesPatchSubmissionResponse( + status=TypesSubmissionStatus.SubmissionStatusAccepted, patch_id="patch-123" + ) # Setup patch API mock mock_patch_api = Mock() @@ -215,12 +221,14 @@ class TestCompetitionAPI: # Verify result assert result[0] == "patch-123" - assert result[1] == TypesSubmissionStatus.ACCEPTED + assert result[1] == TypesSubmissionStatus.SubmissionStatusAccepted def test_get_patch_status(self, competition_api): # Setup mock mock_patch_api = Mock() - mock_patch_api.v1_task_task_id_patch_patch_id_get.return_value = Mock(status=TypesSubmissionStatus.PASSED) + mock_patch_api.v1_task_task_id_patch_patch_id_get.return_value = Mock( + status=TypesSubmissionStatus.SubmissionStatusPassed + ) # Patch the PatchApi constructor with patch("buttercup.orchestrator.scheduler.submissions.PatchApi", return_value=mock_patch_api): @@ -231,7 +239,7 @@ class TestCompetitionAPI: mock_patch_api.v1_task_task_id_patch_patch_id_get.assert_called_once_with( task_id="task-123", patch_id="patch-456" ) - assert status == TypesSubmissionStatus.PASSED + assert status == TypesSubmissionStatus.SubmissionStatusPassed def test_submit_bundle_successful(self, competition_api): # Setup test data @@ -240,7 +248,9 @@ class TestCompetitionAPI: patch_id = "patch-789" # Setup mock response - mock_response = TypesBundleSubmissionResponse(status=TypesSubmissionStatus.ACCEPTED, bundle_id="bundle-123") + mock_response = TypesBundleSubmissionResponse( + status=TypesSubmissionStatus.SubmissionStatusAccepted, bundle_id="bundle-123" + ) # Setup bundle API mock mock_bundle_api = Mock() @@ -260,7 +270,7 @@ class TestCompetitionAPI: # Verify result assert result[0] == "bundle-123" - assert result[1] == TypesSubmissionStatus.ACCEPTED + assert result[1] == TypesSubmissionStatus.SubmissionStatusAccepted def test_submit_matching_sarif_successful(self, competition_api): # Setup test data @@ -268,7 +278,7 @@ class TestCompetitionAPI: sarif_id = "sarif-456" # Setup mock response - mock_response = Mock(status=TypesSubmissionStatus.ACCEPTED) + mock_response = Mock(status=TypesSubmissionStatus.SubmissionStatusAccepted) # Setup sarif API mock mock_sarif_api = Mock() @@ -286,14 +296,14 @@ class TestCompetitionAPI: # Verify result assert result[0] is True - assert result[1] == TypesSubmissionStatus.ACCEPTED + assert result[1] == TypesSubmissionStatus.SubmissionStatusAccepted # Tests for the Submissions class class TestSubmissions: def test_submit_vulnerability_successful(self, submissions, mock_competition_api, sample_crash, mock_redis): # Setup mock return value for submit_vulnerability - mock_competition_api.submit_pov.return_value = ("test-pov-123", TypesSubmissionStatus.ACCEPTED) + mock_competition_api.submit_pov.return_value = ("test-pov-123", TypesSubmissionStatus.SubmissionStatusAccepted) mock_redis.rpush.return_value = 1 # Index of the inserted entry # Call the method @@ -315,7 +325,7 @@ class TestSubmissions: def test_submit_vulnerability_failed(self, submissions, mock_competition_api, sample_crash): # Setup mock to return an error - mock_competition_api.submit_pov.return_value = (None, TypesSubmissionStatus.FAILED) + mock_competition_api.submit_pov.return_value = (None, TypesSubmissionStatus.SubmissionStatusFailed) # Call the method result = submissions.submit_vulnerability(sample_crash) @@ -331,7 +341,7 @@ class TestSubmissions: def test_submit_vulnerability_errored(self, submissions, mock_competition_api, sample_crash): # Setup mock to return an error - mock_competition_api.submit_pov.return_value = (None, TypesSubmissionStatus.ERRORED) + mock_competition_api.submit_pov.return_value = (None, TypesSubmissionStatus.SubmissionStatusErrored) # Call the method result = submissions.submit_vulnerability(sample_crash) @@ -396,7 +406,7 @@ class TestStateTransitions: submissions.entries = [sample_submission_entry] # Mock competition API to return PASSED - mock_competition_api.get_pov_status.return_value = TypesSubmissionStatus.PASSED + mock_competition_api.get_pov_status.return_value = TypesSubmissionStatus.SubmissionStatusPassed # Simulate process_cycle submissions.process_cycle() @@ -410,7 +420,7 @@ class TestStateTransitions: submissions.entries = [sample_submission_entry] # Mock competition API to return FAILED - mock_competition_api.get_pov_status.return_value = TypesSubmissionStatus.FAILED + mock_competition_api.get_pov_status.return_value = TypesSubmissionStatus.SubmissionStatusFailed # Simulate process_cycle submissions.process_cycle() @@ -424,8 +434,8 @@ class TestStateTransitions: submissions.entries = [sample_submission_entry] # Mock competition API to return ERRORED then successful resubmission - mock_competition_api.get_pov_status.return_value = TypesSubmissionStatus.ERRORED - mock_competition_api.submit_pov.return_value = ("new-pov-456", TypesSubmissionStatus.ACCEPTED) + mock_competition_api.get_pov_status.return_value = TypesSubmissionStatus.SubmissionStatusErrored + mock_competition_api.submit_pov.return_value = ("new-pov-456", TypesSubmissionStatus.SubmissionStatusAccepted) # Simulate process_cycle submissions.process_cycle() @@ -445,7 +455,10 @@ class TestStateTransitions: submissions.entries = [sample_submission_entry] # Mock competition API to return successful patch submission - mock_competition_api.submit_patch.return_value = ("test-patch-123", TypesSubmissionStatus.ACCEPTED) + mock_competition_api.submit_patch.return_value = ( + "test-patch-123", + TypesSubmissionStatus.SubmissionStatusAccepted, + ) # Mock the _have_more_patches function to avoid AttributeError with patch("buttercup.orchestrator.scheduler.submissions._have_more_patches", return_value=True): @@ -464,7 +477,7 @@ class TestStateTransitions: submissions.entries = [sample_submission_entry] # Mock competition API to return PASSED - mock_competition_api.get_patch_status.return_value = TypesSubmissionStatus.PASSED + mock_competition_api.get_patch_status.return_value = TypesSubmissionStatus.SubmissionStatusPassed # Simulate process_cycle submissions.process_cycle() @@ -484,7 +497,7 @@ class TestStateTransitions: submissions.entries = [sample_submission_entry] # Mock competition API to return FAILED - mock_competition_api.get_patch_status.return_value = TypesSubmissionStatus.FAILED + mock_competition_api.get_patch_status.return_value = TypesSubmissionStatus.SubmissionStatusFailed # Mock the _advance_patch_idx function to avoid AttributeError with patch("buttercup.orchestrator.scheduler.submissions._advance_patch_idx") as mock_advance: @@ -505,7 +518,10 @@ class TestStateTransitions: submissions.entries = [sample_submission_entry] # Mock competition API to return successful bundle submission - mock_competition_api.submit_bundle.return_value = ("test-bundle-789", TypesSubmissionStatus.ACCEPTED) + mock_competition_api.submit_bundle.return_value = ( + "test-bundle-789", + TypesSubmissionStatus.SubmissionStatusAccepted, + ) # Simulate process_cycle submissions.process_cycle() @@ -522,7 +538,7 @@ class TestStateTransitions: submissions.entries = [sample_submission_entry] # Mock competition API to return failed bundle submission - mock_competition_api.submit_bundle.return_value = (None, TypesSubmissionStatus.FAILED) + mock_competition_api.submit_bundle.return_value = (None, TypesSubmissionStatus.SubmissionStatusFailed) # Simulate process_cycle submissions.process_cycle() @@ -538,7 +554,7 @@ class TestStateTransitions: submissions.entries = [sample_submission_entry] # Mock competition API to return error - mock_competition_api.submit_bundle.return_value = (None, TypesSubmissionStatus.ERRORED) + mock_competition_api.submit_bundle.return_value = (None, TypesSubmissionStatus.SubmissionStatusErrored) # Simulate process_cycle submissions.process_cycle() @@ -581,7 +597,7 @@ class TestStateTransitions: submissions.entries = [sample_submission_entry] # Mock competition API to return successful bundle patch - mock_competition_api.patch_bundle.return_value = (True, TypesSubmissionStatus.ACCEPTED) + mock_competition_api.patch_bundle.return_value = (True, TypesSubmissionStatus.SubmissionStatusAccepted) # Simulate process_cycle submissions.process_cycle() @@ -665,7 +681,10 @@ class TestStateTransitions: # Mock the _task_id function to verify it's being called with the right arguments with patch("buttercup.orchestrator.scheduler.submissions._task_id", return_value=task_id) as mock_task_id: # Mock competition API to return successful patch submission - mock_competition_api.submit_patch.return_value = ("test-patch-123", TypesSubmissionStatus.ACCEPTED) + mock_competition_api.submit_patch.return_value = ( + "test-patch-123", + TypesSubmissionStatus.SubmissionStatusAccepted, + ) # Simulate process_cycle submissions.process_cycle()