From cda29f70c06857d6ce4eb24c2156e9da20e03fb7 Mon Sep 17 00:00:00 2001 From: Veetaha Date: Mon, 18 Mar 2024 21:53:42 +0000 Subject: [PATCH] Next iteratio --- deny.schema.yml | 196 ++++++++++++++++++++++--- deny.template.toml | 13 +- deny.schema.json => deny15.schema.json | 175 +++++++++++++++++++--- 3 files changed, 338 insertions(+), 46 deletions(-) rename deny.schema.json => deny15.schema.json (51%) diff --git a/deny.schema.yml b/deny.schema.yml index 924b6461..492fa06b 100644 --- a/deny.schema.yml +++ b/deny.schema.yml @@ -22,15 +22,16 @@ # still use it since extra properties don't break compatibility and there may # be other TOML LSPs that support newer versions of the JSON schema spec or # existing ones may be updated to support newer versions +# +# We also use some custom extensions by different TOML LSPs, such as `x-taplo` +# to provide better documentation. $schema: https://json-schema.org/draft-07/schema# $id: https://github.com/EmbarkStudios/cargo-deny/deny.schema.json title: cargo-deny configuration file -description: > - You can find the full documentation for the config file at - https://embarkstudios.github.io/cargo-deny/checks/cfg.html +description: Full documentation is at https://embarkstudios.github.io/cargo-deny/checks/cfg.html type: object properties: @@ -50,10 +51,8 @@ definitions: db-urls: type: array items: { type: string, format: uri } - description: | - URLs to one or more advisory databases. - - Default: [RustSec Advisory DB](https://github.com/RustSec/advisory-db) + default: [https://github.com/RustSec/advisory-db] + description: URLs to one or more advisory databases. db-path: type: string @@ -92,27 +91,181 @@ definitions: vulnerability: deprecated: true + oneOf: [{ $ref: '#/definitions/lint-level' }] + default: deny description: | **DEPRECATED** (see `version` field) Determines what happens when a crate with a security vulnerability is encountered. - - `deny` (default) - Will emit an error with details about each vulnerability, and fail the check. - - `warn` - Prints a warning for each vulnerability, but does not fail the check. - - `allow` - Prints a note about the security vulnerability, but does not fail the check. - unmaintained: deprecated: true - enum: [deny, warn, allow] - x-taplo: - docs: - enumValues: - - Will emit an error with details about the problem, and fail the check. - - Prints a warning for each propblem, but does not fail the check. - - Prints a note about the problem, but does not fail the check. + oneOf: [{ $ref: '#/definitions/lint-level' }] + default: warn description: | + **DEPRECATED** (see `version` field) + Determines what happens when a crate with an `unmaintained` advisory is encountered. - Default: warn + + unsound: + deprecated: true + oneOf: [{ $ref: '#/definitions/lint-level' }] + default: warn + description: | + **DEPRECATED** (see `version` field) + + Determines what happens when a crate with an `unsound` advisory is encountered. + + notice: + oneOf: [{ $ref: '#/definitions/lint-level' }] + default: warn + description: | + **DEPRECATED** (see `version` field) + + Determines what happens when a crate with a `notice` advisory is encountered. + + **NOTE**: As of 2019-12-17 there are no `notice` advisories in the + [RustSec Advisory DB](https://github.com/RustSec/advisory-db) + + yanked: + oneOf: [{ $ref: '#/definitions/lint-level' }] + default: warn + description: | + Determines what happens when a crate with a version that has been yanked from its source + registry is encountered. + + ignore: + type: array + items: { $ref: '#/definitions/advisories-ignore-item' } + + advisories-ignore-item: + oneOf: + - type: string + description: Either an advisory ID (e.g. `RUSTSEC-2019-0001`) or a package spec (e.g. `yanked@0.1.1`). + - { $ref: '#/definitions/ignore-advisory-object' } + - { $ref: '#/definitions/ignore-yanked-object' } + + description: | + ```toml + ignore = [ + "RUSTSEC-0000-0000", + { id = "RUSTSEC-0000-0000", reason = "this vulnerability does not affect us as we don't use the particular code path" }, + "yanked@0.1.1", + { crate = "yanked-crate@0.1.1", reason = "a semver compatible version hasn't been published yet" }, + ] + ``` + + Every advisory in the advisory database contains a unique identifier, eg. `RUSTSEC-2019-0001`. + Putting an identifier in this array will cause the advisory to be treated as a note, rather + than a warning or error. + + In addition, yanked crate versions can be ignored by specifying a [PackageSpec](https://embarkstudios.github.io/cargo-deny/checks/cfg.html#package-spec) + with an optional `reason`. + + ignore-advisory-object: + type: object + examples: [RUSTSEC-2019-0001] + required: [id] + properties: + id: + type: string + description: The unique identifier of the advisory to ignore + reason: { $ref: '#/definitions/ignore-reason' } + + ignore-yanked-object: + type: object + required: [crate] + properties: + crate: { $ref: '#/definitions/package-spec' } + reason: { $ref: '#/definitions/ignore-reason' } + + + ignore-reason: + type: string + description: Free-form string that can be used to describe the reason why the advisory is ignored. + + lint-level: + deprecated: true + enum: [deny, warn, allow] + x-taplo: + docs: + enumValues: + - Emit an error with details about the problem, and fail the check. + - Print a warning for each propblem, but don't fail the check. + - Print a note about the problem, but don't fail the check. + + package-spec: + type: string + description: | + Many configuration options require a package specifier at a minimum, which we'll describe here. + The options that use package specifiers will be called out in their individual documentation. + We'll use the [`bans.deny`](bans/cfg.md#the-deny-field-optional) option in the following examples. + + ### String format + + If the particular only requires a package spec at a minimum, then the string format can be used, + which comes in three forms. + + #### Simple + + ```toml + # Will match any version of the simple crate + deny = ["simple"] + ``` + + The simplest string is one which is just the crate name. In this case, the version requirement + used when checking will be `*` meaning it will match against all versions of that crate in the graph. + + #### With Version Requirements + + ```toml + # Will match only these versions of the simple crate that match the predicate(s) + deny = ["simple:<=0.1,>0.2"] + ``` + + If you want to apply version requirements (predicates) to the crate, simply append them following + a `:` separator. + + #### Exact + + ```toml + # Will match only this exact version of the simple crate + deny = [ + "simple@0.1.0", + # This is semantically equivalent to the above + "simple:=0.1.0", + ] + ``` + + The exact form is a specialization of the version requirements, where the semver after the `@` + is transformed to be [= (Exact)](https://docs.rs/semver/latest/semver/enum.Op.html#opexact). + + ### Table format + + #### Crate format + + ```toml + deny = [ + { crate = "simple@0.1.0" }, # equivalent to "simple@0.1.0" + { crate = "simple", wrappers = ["example"] }, + ] + ``` + + The crate format is a replacement for the old `name` and/or `version` table format. It uses + the string format described above in a single `crate` key. + + #### Old format + + ```toml + deny = [ + { name = "simple" }, + { name = "simple", version = "*" } + { name = "simple", wrappers = ["example"] } + ] + ``` + + The old format uses a required `name` key and an optional `version` key. This format is deprecated + and should not be used. graph: description: | @@ -128,7 +281,7 @@ definitions: By default, cargo-deny will consider every single crate that is resolved by cargo, including target specific dependencies e.g. - ```ini + ```toml [target.x86_64-pc-windows-msvc.dependencies] winapi = "0.3.8" @@ -217,7 +370,8 @@ definitions: feature-depth: type: integer minimum: 0 + default: 1 description: | The maximum depth that features will be displayed when inclusion graphs are included in diagnostics, unless specified via `--feature-depth` on the command line. Only applies to - diagnostics that actually print features. If not specified defaults to `1`. + diagnostics that actually print features. diff --git a/deny.template.toml b/deny.template.toml index 700e4082..dcaad1a8 100644 --- a/deny.template.toml +++ b/deny.template.toml @@ -1,4 +1,4 @@ -#:schema ./deny.schema.json +#:schema deny15.schema.json # This template contains all of the possible sections and their default values @@ -65,6 +65,7 @@ feature-depth = 1 # More documentation for the advisories section can be found here: # https://embarkstudios.github.io/cargo-deny/checks/advisories/cfg.html [advisories] + # The path where the advisory databases are cloned/fetched into #db-path = "$CARGO_HOME/advisory-dbs" # The url(s) of the advisory databases to use @@ -72,11 +73,13 @@ feature-depth = 1 # A list of advisory IDs to ignore. Note that ignored advisories will still # output a note when they are encountered. ignore = [ - #"RUSTSEC-0000-0000", - #{ id = "RUSTSEC-0000-0000", reason = "you can specify a reason the advisory is ignored" }, - #"a-crate-that-is-yanked@0.1.1", # you can also ignore yanked crate versions if you wish - #{ crate = "a-crate-that-is-yanked@0.1.1", reason = "you can specify why you are ignoring the yanked crate" }, + "RUSTSEC-0000-0000", + { id = "RUSTSEC-0000-0000", reason = "you can specify a reason the advisory is ignored" }, + "a-crate-that-is-yanked@0.1.1", # you can also ignore yanked crate versions if you wish + { crate = "a-crate-that-is-yanked@0.1.1", reason = "you can specify why you are ignoring the yanked crate" }, ] + + # If this is true, then cargo deny will use the git executable to fetch advisory database. # If this is false, then it uses a built-in git library. # Setting this to true can be helpful if you have special authentication requirements that cargo-deny does not support. diff --git a/deny.schema.json b/deny15.schema.json similarity index 51% rename from deny.schema.json rename to deny15.schema.json index 3a4cbbdc..c4c2eacd 100644 --- a/deny.schema.json +++ b/deny15.schema.json @@ -2,7 +2,7 @@ "$schema": "https://json-schema.org/draft-07/schema#", "$id": "https://github.com/EmbarkStudios/cargo-deny/deny.schema.json", "title": "cargo-deny configuration file", - "description": "You can find the full documentation for the config file at https://embarkstudios.github.io/cargo-deny/checks/cfg.html\n", + "description": "Full documentation is at https://embarkstudios.github.io/cargo-deny/checks/cfg.html", "type": "object", "properties": { @@ -35,7 +35,11 @@ "type": "string", "format": "uri" }, - "description": "URLs to one or more advisory databases.\n\nDefault: [RustSec Advisory DB](https://github.com/RustSec/advisory-db)\n" + "default": + [ + "https://github.com/RustSec/advisory-db" + ], + "description": "URLs to one or more advisory databases." }, "db-path": { @@ -53,33 +57,163 @@ "vulnerability": { "deprecated": true, - "description": "**DEPRECATED** (see `version` field)\n\nDetermines what happens when a crate with a security vulnerability is encountered.\n\n- `deny` (default) - Will emit an error with details about each vulnerability, and fail the check.\n- `warn` - Prints a warning for each vulnerability, but does not fail the check.\n- `allow` - Prints a note about the security vulnerability, but does not fail the check.\n" + "oneOf": + [ + { + "$ref": "#/definitions/lint-level" + } + ], + "default": "deny", + "description": "**DEPRECATED** (see `version` field)\n\nDetermines what happens when a crate with a security vulnerability is encountered.\n" }, "unmaintained": { "deprecated": true, - "enum": + "oneOf": [ - "deny", - "warn", - "allow" + { + "$ref": "#/definitions/lint-level" + } ], - "x-taplo": - { - "docs": + "default": "warn", + "description": "**DEPRECATED** (see `version` field)\n\nDetermines what happens when a crate with an `unmaintained` advisory is encountered.\n" + }, + "unsound": + { + "deprecated": true, + "oneOf": + [ { - "enumValues": - [ - "Will emit an error with details about the problem, and fail the check.", - "Prints a warning for each propblem, but does not fail the check.", - "Prints a note about the problem, but does not fail the check." - ] + "$ref": "#/definitions/lint-level" } - }, - "description": "Determines what happens when a crate with an `unmaintained` advisory is encountered.\nDefault: warn\n" + ], + "default": "warn", + "description": "**DEPRECATED** (see `version` field)\n\nDetermines what happens when a crate with an `unsound` advisory is encountered.\n" + }, + "notice": + { + "oneOf": + [ + { + "$ref": "#/definitions/lint-level" + } + ], + "default": "warn", + "description": "**DEPRECATED** (see `version` field)\n\nDetermines what happens when a crate with a `notice` advisory is encountered.\n\n**NOTE**: As of 2019-12-17 there are no `notice` advisories in the\n[RustSec Advisory DB](https://github.com/RustSec/advisory-db)\n" + }, + "yanked": + { + "oneOf": + [ + { + "$ref": "#/definitions/lint-level" + } + ], + "default": "warn", + "description": "Determines what happens when a crate with a version that has been yanked from its source\nregistry is encountered.\n" + }, + "ignore": + { + "type": "array", + "items": + { + "$ref": "#/definitions/advisories-ignore-item" + } } } }, + "advisories-ignore-item": + { + "oneOf": + [ + { + "type": "string", + "description": "Either an advisory ID (e.g. `RUSTSEC-2019-0001`) or a package spec (e.g. `yanked@0.1.1`)." + }, + { + "$ref": "#/definitions/ignore-advisory-object" + }, + { + "$ref": "#/definitions/ignore-yanked-object" + } + ], + "description": "```toml\nignore = [\n \"RUSTSEC-0000-0000\",\n { id = \"RUSTSEC-0000-0000\", reason = \"this vulnerability does not affect us as we don't use the particular code path\" },\n \"yanked@0.1.1\",\n { crate = \"yanked-crate@0.1.1\", reason = \"a semver compatible version hasn't been published yet\" },\n]\n```\n\nEvery advisory in the advisory database contains a unique identifier, eg. `RUSTSEC-2019-0001`.\nPutting an identifier in this array will cause the advisory to be treated as a note, rather\nthan a warning or error.\n\nIn addition, yanked crate versions can be ignored by specifying a [PackageSpec](https://embarkstudios.github.io/cargo-deny/checks/cfg.html#package-spec)\nwith an optional `reason`.\n" + }, + "ignore-advisory-object": + { + "type": "object", + "examples": + [ + "RUSTSEC-2019-0001" + ], + "required": + [ + "id" + ], + "properties": + { + "id": + { + "type": "string", + "description": "The unique identifier of the advisory to ignore" + }, + "reason": + { + "$ref": "#/definitions/ignore-reason" + } + } + }, + "ignore-yanked-object": + { + "type": "object", + "required": + [ + "crate" + ], + "properties": + { + "crate": + { + "$ref": "#/definitions/package-spec" + }, + "reason": + { + "$ref": "#/definitions/ignore-reason" + } + } + }, + "ignore-reason": + { + "type": "string", + "description": "Free-form string that can be used to describe the reason why the advisory is ignored." + }, + "lint-level": + { + "deprecated": true, + "enum": + [ + "deny", + "warn", + "allow" + ], + "x-taplo": + { + "docs": + { + "enumValues": + [ + "Emit an error with details about the problem, and fail the check.", + "Print a warning for each propblem, but don't fail the check.", + "Print a note about the problem, but don't fail the check." + ] + } + } + }, + "package-spec": + { + "type": "string", + "description": "Many configuration options require a package specifier at a minimum, which we'll describe here.\nThe options that use package specifiers will be called out in their individual documentation.\nWe'll use the [`bans.deny`](bans/cfg.md#the-deny-field-optional) option in the following examples.\n\n### String format\n\nIf the particular only requires a package spec at a minimum, then the string format can be used,\nwhich comes in three forms.\n\n#### Simple\n\n```toml\n# Will match any version of the simple crate\ndeny = [\"simple\"]\n```\n\nThe simplest string is one which is just the crate name. In this case, the version requirement\nused when checking will be `*` meaning it will match against all versions of that crate in the graph.\n\n#### With Version Requirements\n\n```toml\n# Will match only these versions of the simple crate that match the predicate(s)\ndeny = [\"simple:<=0.1,>0.2\"]\n```\n\nIf you want to apply version requirements (predicates) to the crate, simply append them following\na `:` separator.\n\n#### Exact\n\n```toml\n# Will match only this exact version of the simple crate\ndeny = [\n \"simple@0.1.0\",\n # This is semantically equivalent to the above\n \"simple:=0.1.0\",\n]\n```\n\nThe exact form is a specialization of the version requirements, where the semver after the `@`\nis transformed to be [= (Exact)](https://docs.rs/semver/latest/semver/enum.Op.html#opexact).\n\n### Table format\n\n#### Crate format\n\n```toml\ndeny = [\n { crate = \"simple@0.1.0\" }, # equivalent to \"simple@0.1.0\"\n { crate = \"simple\", wrappers = [\"example\"] },\n]\n```\n\nThe crate format is a replacement for the old `name` and/or `version` table format. It uses\nthe string format described above in a single `crate` key.\n\n#### Old format\n\n```toml\ndeny = [\n { name = \"simple\" },\n { name = \"simple\", version = \"*\" }\n { name = \"simple\", wrappers = [\"example\"] }\n]\n```\n\nThe old format uses a required `name` key and an optional `version` key. This format is deprecated\nand should not be used.\n" + }, "graph": { "description": "The graph table configures how the dependency graph is constructed and thus which crates the\nchecks are performed against\n", @@ -93,7 +227,7 @@ { "$ref": "#/definitions/target" }, - "description": "By default, cargo-deny will consider every single crate that is resolved by cargo, including\ntarget specific dependencies e.g.\n\n```ini\n[target.x86_64-pc-windows-msvc.dependencies]\nwinapi = \"0.3.8\"\n\n[target.'cfg(target_os = \"fuchsia\")'.dependencies]\nfuchsia-cprng = \"0.1.1\"\n```\n\nBut unless you are actually targeting `x86_64-fuchsia` or `aarch64-fuchsia`, the `fuchsia-cprng` is\nnever actually going to be compiled or linked into your project, so checking it is pointless for you.\n\nThe `targets` field allows you to specify one or more targets which you **actually** build for.\nEvery dependency link to a crate is checked against this list, and if none of the listed targets\nsatisfy the target constraint, the dependency link is ignored. If a crate has no dependency links\nto it, it is not included into the crate graph that the checks are\nexecuted against.\n" + "description": "By default, cargo-deny will consider every single crate that is resolved by cargo, including\ntarget specific dependencies e.g.\n\n```toml\n[target.x86_64-pc-windows-msvc.dependencies]\nwinapi = \"0.3.8\"\n\n[target.'cfg(target_os = \"fuchsia\")'.dependencies]\nfuchsia-cprng = \"0.1.1\"\n```\n\nBut unless you are actually targeting `x86_64-fuchsia` or `aarch64-fuchsia`, the `fuchsia-cprng` is\nnever actually going to be compiled or linked into your project, so checking it is pointless for you.\n\nThe `targets` field allows you to specify one or more targets which you **actually** build for.\nEvery dependency link to a crate is checked against this list, and if none of the listed targets\nsatisfy the target constraint, the dependency link is ignored. If a crate has no dependency links\nto it, it is not included into the crate graph that the checks are\nexecuted against.\n" }, "exclude": { @@ -177,7 +311,8 @@ { "type": "integer", "minimum": 0, - "description": "The maximum depth that features will be displayed when inclusion graphs are included in\ndiagnostics, unless specified via `--feature-depth` on the command line. Only applies to\ndiagnostics that actually print features. If not specified defaults to `1`.\n" + "default": 1, + "description": "The maximum depth that features will be displayed when inclusion graphs are included in\ndiagnostics, unless specified via `--feature-depth` on the command line. Only applies to\ndiagnostics that actually print features.\n" } } }