Skip to content

Commit 67491f7

Browse files
jasonforaljasonforal
authored
Merge pull request #856 from DataDog/jf/K9VULN-11777-1
[K9VULN-11777] Add summarized legacy config doc
2 parents a0a8f37 + bd42463 commit 67491f7

1 file changed

Lines changed: 131 additions & 0 deletions

File tree

‎doc/legacy_config.md‎

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
# Legacy Configuration File
2+
The static analyzer has backwards-compatible support for the legacy `static-analysis.datadog.yml` configuration file,
3+
which has a different schema and semantics than the current configuration schema (See: [Configuration file](https://github.com/DataDog/datadog-static-analyzer?tab=readme-ov-file#configuration-file)).
4+
5+
Users may continue to use their `static-analysis.datadog.yml` configuration file with no disruptions or behavior
6+
changes. A migration tool will be provided in the future.
7+
8+
Documentation for this format has been saved below for reference:
9+
10+
---
11+
12+
## Legacy Schema Reference
13+
14+
The static analyzer can be configured using a `static-analysis.datadog.yml` file
15+
at the root directory of the repository. This is a YAML file with the following entries:
16+
17+
- `rulesets`: (required) a list with all the rulesets to use for this repository (see [Datadog Documentation](https://docs.datadoghq.com/security/code_security/static_analysis/static_analysis_rules/) for a full list). The elements of this list must be strings or maps containing a configuration for a ruleset (described below.)
18+
- `ignore`: (optional) a list of path prefixes and glob patterns to ignore. A file that matches any of its entries will not be analyzed.
19+
- `only`: (optional) a list of path prefixes and glob patterns to analyze. If `only` is specified, only files that match one of its entries will be analyzed.
20+
- `ignore-gitignore`: (optional) by default, any entries found in the `.gitignore` file are added to the `ignore` list. If the `ignore-gitignore` option is true, the `.gitignore` file is not read.
21+
- `max-file-size-kb`: (optional) files larger than this size, in kilobytes, will be ignored. The default value is 200 kB.
22+
- `schema-version`: (optional) the version of the schema that this configuration file follows. If specified, it must be `v1`.
23+
24+
The entries of the `rulesets` list must be strings that contain the name of a ruleset to enable, or a map that contains the configuration for a ruleset. This map contains the following fields:
25+
26+
- the first field (required) gives the ruleset name as its key, with an empty value.
27+
- `ignore`: (optional) a list of path prefixes and glob patterns to ignore _for this ruleset_. Rules in this ruleset will not be evaluated for any files that match any of the entries in the `ignore` list.
28+
- `only`: (optional) a list of path prefixes and glob patterns to analyze _for this ruleset_. If `only` is specified, rules in this ruleset will only be evaluated for files that match one of the entries.
29+
- `rules`: (optional) a map of rule configurations. Rules not specified in this map will still be evaluated, but with their default configuration.
30+
31+
The map in the `rules` field uses the rule's name as its key, and the values are maps with the following fields:
32+
33+
- `ignore` (optional) a list of path prefixes and glob patterns to ignore _for this rule_. This rule will not be evaluated for any files that match any of the entries in the `ignore` list.
34+
- `only`: (optional) a list of path prefixes and glob patterns to analyze _for this rule_. If `only` is specified, this rule will only be evaluated for files that match one of the entries.
35+
- `severity`: (optional) if provided, override the severity of violations produced by this rule. The valid severities are `ERROR`, `WARNING`, `NOTICE`, and `NONE`.
36+
- `category`: (optional) if provided, override this rule's category. The valid categories are `BEST_PRACTICES`, `CODE_STYLE`, `ERROR_PRONE`, `PERFORMANCE`, and `SECURITY`.
37+
- `arguments`: (optional) a map of values for the rule's arguments.
38+
39+
The map in the `arguments` field uses an argument's name as its key, and the values are either strings or maps:
40+
41+
- if you want to set a value for the whole repository, you can specify it as a string;
42+
- if you want to set different values for different subtrees in the repository, you can specify them as a map from a subtree prefix to the value that the argument will have within that subtree. See the example for more details.
43+
44+
An annotated example of a configuration file:
45+
46+
```yaml
47+
# The list of rulesets to enable for this repository.
48+
rulesets:
49+
# Enable the `python-inclusive` ruleset with the default configuration.
50+
- python-inclusive
51+
# Enable the `python-best-practices` ruleset with a custom configuration.
52+
- python-best-practices:
53+
# Do not apply any of the rules in this ruleset to files that match `src/**/*.generated.py`.
54+
ignore:
55+
- src/**/*.generated.py
56+
rules:
57+
# Special configuration for the `python-best-practices/no-generic-exception` rule.
58+
no-generic-exception:
59+
# Treat violations of this rule as errors (normally "notice").
60+
severity: ERROR
61+
# Classify violations of this rule under the "code style" category.
62+
category: CODE_STYLE
63+
# Only apply this rule to files under the `src/new-code` subtree.
64+
only:
65+
- src/new-code
66+
# Enable the `python-code-style ruleset` with a custom configuration.
67+
- python-code-style:
68+
rules:
69+
max-function-lines:
70+
# Set arguments for the `python-code-style/max-function-lines` rule.
71+
arguments:
72+
# Set the `max-lines` argument to 150 in the whole repository.
73+
max-lines: 150
74+
max-class-lines:
75+
# Set arguments for the `python-code-style/max-class-lines` rule.
76+
arguments:
77+
# Set different values for the `max-lines` argument in different subtrees.
78+
max-lines:
79+
# Set the `max-lines` argument to 100 by default
80+
/: 100
81+
# Set the `max-lines` argument to 75 under the `src/new-code` subtree.
82+
src/new-code: 75
83+
# Analyze only files in the `src` and `imported` subtrees.
84+
only:
85+
- src
86+
- imported
87+
# Do not analyze any files in the `src/tests` subtree.
88+
ignore:
89+
- src/tests
90+
# Do not add the content of the `.gitignore` file to the `ignore` list.
91+
ignore-gitignore: true
92+
# Do not analyze files larger than 100 kB.
93+
max-file-size-kb: 100
94+
```
95+
96+
Another example that shows every option being used:
97+
98+
```yaml
99+
rulesets:
100+
- python-best-practices
101+
- python-code-style:
102+
ignore:
103+
- src/generated
104+
- src/**/*_test.py
105+
only:
106+
- src
107+
- imported/**/new/**
108+
rules:
109+
max-function-lines:
110+
severity: WARNING
111+
category: PERFORMANCE
112+
ignore:
113+
- src/new-code
114+
- src/new/*.gen.py
115+
only:
116+
- src/new
117+
- src/**/new-code/**
118+
arguments:
119+
max-lines: 150
120+
min-lines:
121+
/: 10
122+
src/new-code: 0
123+
ignore:
124+
- dist
125+
- lib/**/*.py
126+
only:
127+
- src
128+
- imported/**/*.py
129+
ignore-gitignore: true
130+
max-file-size-kb: 256
131+
```

0 commit comments

Comments
 (0)