diff --git a/deny.schema.json b/deny.schema.json new file mode 100644 index 00000000..3a4cbbdc --- /dev/null +++ b/deny.schema.json @@ -0,0 +1,185 @@ +{ + "$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", + "type": "object", + "properties": + { + "advisories": + { + "$ref": "#/definitions/advisories" + }, + "graph": + { + "$ref": "#/definitions/graph" + }, + "output": + { + "$ref": "#/definitions/output" + } + }, + "definitions": + { + "advisories": + { + "description": "This section is considered when running `cargo deny check advisories`\nMore documentation for the advisories section can be found here:\nhttps://embarkstudios.github.io/cargo-deny/checks/advisories/cfg.html\n", + "type": "object", + "properties": + { + "db-urls": + { + "type": "array", + "items": + { + "type": "string", + "format": "uri" + }, + "description": "URLs to one or more advisory databases.\n\nDefault: [RustSec Advisory DB](https://github.com/RustSec/advisory-db)\n" + }, + "db-path": + { + "type": "string", + "description": "Path to the root directory into which one or more advisory databases are cloned into.\n\nThis value supports basic shell expansion:\n\n- `~` - Expands to [`home::home_dir`](https://docs.rs/home/latest/home/fn.home_dir.html)\n- `$VARNAME` - Expands to [`std::env::var(\"VARNAME\")`](https://doc.rust-lang.org/std/env/fn.var.html)\n- `${VARNAME}` - Expands to [`std::env::var(\"VARNAME\")`](https://doc.rust-lang.org/std/env/fn.var.html)\n- `${VARNAME:-fallback}` - Expands to [`std::env::var(\"VARNAME\")`](https://doc.rust-lang.org/std/env/fn.var.html)\n or the fallback value if it doesn't exist (everything between the `:-` and `}`)\n- `$CARGO_HOME` - Expands to [`std::env::var(\"CARGO_HOME\")`](https://doc.rust-lang.org/std/env/fn.var.html)\n if it exists, otherwise expands to `$(home::home_dir())/.cargo`\n\nNote that the path must be valid utf-8, after expansion.\n\nDefault: `$CARGO_HOME/advisory-dbs`\n" + }, + "version": + { + "enum": + [ + 2 + ], + "description": "The advisories section has an upcoming breaking change, with deprecation warnings for several\nfields that will be removed. Setting `version = 2` will opt-in to the future default behavior.\n\nThe breaking change is as follows:\n\n- `vulnerability` - Removed, all vulnerability advisories now emit errors.\n- `unmaintained` - Removed, all unmaintained advisories now emit errors.\n- `unsound` - Removed, all unsound advisories now emit errors.\n- `notice` - Removed, all notice advisories now emit errors.\n- `severity-threshold` - Removed, all vulnerability advisories now emit errors.\n\nAs before, if you want to ignore a specific advisory, add it to the `ignore` field.\n" + }, + "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" + }, + "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." + ] + } + }, + "description": "Determines what happens when a crate with an `unmaintained` advisory is encountered.\nDefault: warn\n" + } + } + }, + "graph": + { + "description": "The graph table configures how the dependency graph is constructed and thus which crates the\nchecks are performed against\n", + "type": "object", + "properties": + { + "targets": + { + "type": "array", + "items": + { + "$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" + }, + "exclude": + { + "type": "array", + "items": + { + "type": "string" + }, + "description": "Just as with the [`--exclude`](https://embarkstudios.github.io/cargo-deny/cli/common.html#--exclude-dev)\ncommand line option, this field allows you to specify one or more [Package ID specifications](https://doc.rust-lang.org/cargo/commands/cargo-pkgid.html)\nthat will cause the crate(s) in question to be excluded from the crate graph that is used\nfor the operation you are performing.\n\nNote that excluding a crate is recursive, if any of its transitive dependencies are only referenced\nvia the excluded crate, they will also be excluded from the crate graph.\n" + }, + "all-features": + { + "type": "boolean", + "description": "If set to `true`, `--all-features` will be used when collecting metadata." + }, + "no-default-features": + { + "type": "boolean", + "description": "If set to `true`, `--no-default-features` will be used when collecting metadata." + }, + "features": + { + "type": "array", + "items": + { + "type": "string" + }, + "description": "If set, and `--features` is not specified on the cmd line, these features will be used when\ncollecting metadata.\n" + }, + "exclude-dev": + { + "type": "boolean", + "description": "If set to `true`, all `dev-dependencies`, even one for workspace crates, are not included\nin the crate graph used for any of the checks. This option can also be enabled on cmd line\nwith `--exclude-dev` either [before](https://embarkstudios.github.io/cargo-deny/cli/common.html#--exclude-dev)\nor [after](https://embarkstudios.github.io/cargo-deny/cli/check.html#--exclude-dev)\nthe `check` subcommand.\n" + } + } + }, + "target": + { + "oneOf": + [ + { + "$ref": "#/definitions/target-triple" + }, + { + "$ref": "#/definitions/target-object" + } + ] + }, + "target-object": + { + "description": "Advanced configurations to apply for the target triple", + "type": "object", + "required": + [ + "triple" + ], + "properties": + { + "triple": + { + "$ref": "#/definitions/target-triple" + }, + "features": + { + "description": "Rust `cfg()` expressions support the [`target_feature = \"feature-name\"`](https://doc.rust-lang.org/reference/attributes/codegen.html#the-target_feature-attribute)\npredicate, but at the moment, the only way to actually pass them when compiling is to use\nthe `RUSTFLAGS` environment variable. The `features` field allows you to specify 1 or more\n`target_feature`s you plan to build with, for a particular target triple. At the time of\nthis writing, cargo-deny does not attempt to validate that the features you specify are\nactually valid for the target triple, but this is [planned](https://github.com/EmbarkStudios/cfg-expr/issues/1).\n" + } + } + }, + "target-triple": + { + "type": "string", + "description": "The [target triple](https://forge.rust-lang.org/release/platform-support.html) for the target\nyou wish to filter target specific dependencies with. If the target triple specified is **not**\none of the targets builtin to `rustc`, the configuration check for that target will be limited\nto only the raw `[target..dependencies]` style of target configuration, as `cfg()`\nexpressions require us to know the details about the target.\n" + }, + "output": + { + "description": "The output table provides options for how/if diagnostics are outputted", + "type": "object", + "properties": + { + "feature-depth": + { + "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" + } + } + } + } +} \ No newline at end of file diff --git a/deny.schema.yml b/deny.schema.yml new file mode 100644 index 00000000..924b6461 --- /dev/null +++ b/deny.schema.yml @@ -0,0 +1,223 @@ +# yaml-language-server: $schema=https://json-schema.org/draft-07/schema# + +# Welcome to the JSON Schema for the `deny.toml` configuration file 🥰. +# This file is used to provide IDE completions and documentation for it. +# It is maintained by hand, and seves as the source of truth for the JSON schema. +# +# The schema is written in YAML since it permits comments, multi-line strings +# and generally is easier to write by humans directly. We convert it to JSON +# after edits and check the generated JSON file into the source control. +# CI validates for the freshness of the JSON version of this file. +# +# The schema uses 'draft-07' dialect of the JSON schema since this is the version +# that is supported by the YAML LSP in VSCode at least. There are newer versions +# of the JSON schema spec, and we use some of the features of the newer specs, +# but our goal is to be ultimately compatible with the 'draft-04' version of the +# spec, which is supported by "Even Better TOML" VSCode extension (taplo): +# https://taplo.tamasfe.dev/configuration/developing-schemas.html. This is likely +# the extension people use when authoring `deny.toml` config files in VSCode. +# +# For example, the `deprecated` property is available only since '2020-12' version +# of the spec. It isn't available in the 'draft-04' and 'draft-07' versions, but we +# 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 + +$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 + +type: object +properties: + advisories: { $ref: '#/definitions/advisories' } + graph: { $ref: '#/definitions/graph' } + output: { $ref: '#/definitions/output' } + +definitions: + advisories: + description: | + This section is considered when running `cargo deny check advisories` + More documentation for the advisories section can be found here: + https://embarkstudios.github.io/cargo-deny/checks/advisories/cfg.html + + type: object + properties: + 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) + + db-path: + type: string + description: | + Path to the root directory into which one or more advisory databases are cloned into. + + This value supports basic shell expansion: + + - `~` - Expands to [`home::home_dir`](https://docs.rs/home/latest/home/fn.home_dir.html) + - `$VARNAME` - Expands to [`std::env::var("VARNAME")`](https://doc.rust-lang.org/std/env/fn.var.html) + - `${VARNAME}` - Expands to [`std::env::var("VARNAME")`](https://doc.rust-lang.org/std/env/fn.var.html) + - `${VARNAME:-fallback}` - Expands to [`std::env::var("VARNAME")`](https://doc.rust-lang.org/std/env/fn.var.html) + or the fallback value if it doesn't exist (everything between the `:-` and `}`) + - `$CARGO_HOME` - Expands to [`std::env::var("CARGO_HOME")`](https://doc.rust-lang.org/std/env/fn.var.html) + if it exists, otherwise expands to `$(home::home_dir())/.cargo` + + Note that the path must be valid utf-8, after expansion. + + Default: `$CARGO_HOME/advisory-dbs` + + version: + enum: [2] + description: | + The advisories section has an upcoming breaking change, with deprecation warnings for several + fields that will be removed. Setting `version = 2` will opt-in to the future default behavior. + + The breaking change is as follows: + + - `vulnerability` - Removed, all vulnerability advisories now emit errors. + - `unmaintained` - Removed, all unmaintained advisories now emit errors. + - `unsound` - Removed, all unsound advisories now emit errors. + - `notice` - Removed, all notice advisories now emit errors. + - `severity-threshold` - Removed, all vulnerability advisories now emit errors. + + As before, if you want to ignore a specific advisory, add it to the `ignore` field. + + vulnerability: + deprecated: true + 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. + description: | + Determines what happens when a crate with an `unmaintained` advisory is encountered. + Default: warn + + graph: + description: | + The graph table configures how the dependency graph is constructed and thus which crates the + checks are performed against + + type: object + properties: + targets: + type: array + items: { $ref: '#/definitions/target' } + description: | + By default, cargo-deny will consider every single crate that is resolved by cargo, including + target specific dependencies e.g. + + ```ini + [target.x86_64-pc-windows-msvc.dependencies] + winapi = "0.3.8" + + [target.'cfg(target_os = "fuchsia")'.dependencies] + fuchsia-cprng = "0.1.1" + ``` + + But unless you are actually targeting `x86_64-fuchsia` or `aarch64-fuchsia`, the `fuchsia-cprng` is + never actually going to be compiled or linked into your project, so checking it is pointless for you. + + The `targets` field allows you to specify one or more targets which you **actually** build for. + Every dependency link to a crate is checked against this list, and if none of the listed targets + satisfy the target constraint, the dependency link is ignored. If a crate has no dependency links + to it, it is not included into the crate graph that the checks are + executed against. + + exclude: + type: array + items: { type: string } + description: | + Just as with the [`--exclude`](https://embarkstudios.github.io/cargo-deny/cli/common.html#--exclude-dev) + command line option, this field allows you to specify one or more [Package ID specifications](https://doc.rust-lang.org/cargo/commands/cargo-pkgid.html) + that will cause the crate(s) in question to be excluded from the crate graph that is used + for the operation you are performing. + + Note that excluding a crate is recursive, if any of its transitive dependencies are only referenced + via the excluded crate, they will also be excluded from the crate graph. + + all-features: + type: boolean + description: If set to `true`, `--all-features` will be used when collecting metadata. + + no-default-features: + type: boolean + description: If set to `true`, `--no-default-features` will be used when collecting metadata. + + features: + type: array + items: { type: string } + description: | + If set, and `--features` is not specified on the cmd line, these features will be used when + collecting metadata. + + exclude-dev: + type: boolean + description: | + If set to `true`, all `dev-dependencies`, even one for workspace crates, are not included + in the crate graph used for any of the checks. This option can also be enabled on cmd line + with `--exclude-dev` either [before](https://embarkstudios.github.io/cargo-deny/cli/common.html#--exclude-dev) + or [after](https://embarkstudios.github.io/cargo-deny/cli/check.html#--exclude-dev) + the `check` subcommand. + + target: + oneOf: + - $ref: '#/definitions/target-triple' + - $ref: '#/definitions/target-object' + + target-object: + description: Advanced configurations to apply for the target triple + type: object + required: [triple] + properties: + triple: { $ref: '#/definitions/target-triple' } + features: + description: | + Rust `cfg()` expressions support the [`target_feature = "feature-name"`](https://doc.rust-lang.org/reference/attributes/codegen.html#the-target_feature-attribute) + predicate, but at the moment, the only way to actually pass them when compiling is to use + the `RUSTFLAGS` environment variable. The `features` field allows you to specify 1 or more + `target_feature`s you plan to build with, for a particular target triple. At the time of + this writing, cargo-deny does not attempt to validate that the features you specify are + actually valid for the target triple, but this is [planned](https://github.com/EmbarkStudios/cfg-expr/issues/1). + + target-triple: + type: string + description: | + The [target triple](https://forge.rust-lang.org/release/platform-support.html) for the target + you wish to filter target specific dependencies with. If the target triple specified is **not** + one of the targets builtin to `rustc`, the configuration check for that target will be limited + to only the raw `[target..dependencies]` style of target configuration, as `cfg()` + expressions require us to know the details about the target. + + output: + description: The output table provides options for how/if diagnostics are outputted + type: object + properties: + feature-depth: + type: integer + minimum: 0 + 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`. diff --git a/deny.template.toml b/deny.template.toml index f38a8f23..700e4082 100644 --- a/deny.template.toml +++ b/deny.template.toml @@ -1,3 +1,5 @@ +#:schema ./deny.schema.json + # This template contains all of the possible sections and their default values # Note that all fields that take a lint level have these possible values: