Analyze Command

The Analyze command scans a source directory for potential issues, using a default or external set of rules. If the -O argument is provided, output will be written to the provided filename. If -O is not provided, DevSkim will output the scan report to stdout.

Syntax

Usage: devskim analyze [arguments] [options]

Arguments:
  -I, --source-code             Required. Path to a directory containing files to scan or a single file to scan.
  -O, --output-file             Optional. Filename for result file, uses stdout if not set.

Options:
  --options-json                (Default: ) The path to a .json file that contains a serialized SerializedAnalyzeCommandOptions object which can
                                specify both Analyze options and extra options. Options specified explicitly override options from this argument.
  -r                            (Default: ) Comma separated list of paths to rules files to use
  --rule-ids                    (Default: ) Comma separated list of rule IDs to limit analysis to
  --ignore-rule-ids             (Default: ) Comma separated list of rule IDs to ignore
  --languages                   (Default: ) Path to custom json formatted Language file to specify languages, when specified comments must also
                                be specified
  --comments                    (Default: ) Path to custom json formatted Comments file to specify languages, when specified languages must also
                                be specified
  -o, --output-format           (Default: %F:%L:%C:%l:%c [%S] %R %N) Format for output text.
  -f, --file-format             (Default: sarif) Format type for output. [text|sarif]
  -s, --severity                (Default: Critical Important Moderate BestPractice ManualReview) Comma-separated Severities to match
  --confidence                  (Default: High Medium) Comma-separated Severities to match
  -g, --ignore-globs            (Default: **/.git/** **/bin/**) Comma-separated Globs for files to skip analyzing
  -d, --disable-supression      (Default: false) Disable comment suppressions
  --disable-parallel            (Default: false) Disable parallel processing
  -i, --ignore-default-rules    (Default: false) Ignore default rules
  -c, --crawl-archives          (Default: false) Analyze files contained inside of archives
  -E                            (Default: false) Use exit code for number of issues. Negative on error.
  --base-path                   (Default: ) Specify what path to root result URIs in Sarif results with. When not set will generate paths
                                relative to the source directory (or directory containing the source file specified)
  --absolute-path               (Default: false) Output absolute paths (overrides --base-path).
  --skip-git-ignored-files      (Default: false) Set to skip files which are ignored by .gitignore. Requires git to be installed.
  --skip-excerpts               (Default: false) Set to skip gathering excerpts and samples to include in the report.
  -x, --console-verbosity       (Default: Information) Console verbosity [Verbose|Debug|Information|Warning|Error|Fatal]
  --disable-console             (Default: false) Disable console output of logging messages.
  -v, --log-file-level          (Default: Error) Log file level [Verbose|Debug|Information|Warning|Error|Fatal]
  -l, --log-file-path           Log file path. If not set, will not log to file.
  --help                        Display this help screen.
  --version                     Display version information.

Example

devskim analyze -I /home/user/myproject/src/

Configure DevSkim with a json file

DevSkim analysis can be configured with the --options-json option to specify a path on disc of a file to treat as a JSON representation of options to use for analysis. The -I|--source-code argument cannot be specified in the options json. The Options JSON is deserialized as a SerializedAnalyzeCommandOptions object, which supports a mapping to ignore specific rules based on filetype, and any option from the BaseAnalyzeCommandOptions class.

For example, if you wanted to configure the ignore-globs argument via JSON to ignore all .contoso files, and the rule DS123456789 for CSharp you could use this json file

{
  "Globs": [
    "*.contoso"
  ],
  "LanguageRuleIgnoreMap": {
     "csharp" : [ "DS123456789"]
  }
}

And run devskim analyze -I path/to/src/ --options-json path/to/options.json

Any option explicitly specified on the command line will override the option provided in the deserialized json, allowing the JSON to be used as a reusable base configuration.

The following is the full set of configurable options with their default values

{
    "LanguageRuleIgnoreMap": {},
    "OutputFile": "",
    "Rules": [],
    "RuleIds": [],
    "IgnoreRuleIds": [],
    "LanguagesPath": "",
    "CommentsPath": "",
    "OutputTextFormat": "",
    "OutputFileFormat": "",
    "Severities": [
        "Critical",
        "Important",
        "Moderate",
        "BestPractice",
        "ManualReview"
    ],
    "Confidences": [
        "High",
        "Medium"
    ],
    "Globs": [
        "**/.git/**",
        "**/bin/**"
    ],
    "DisableSuppression": false,
    "DisableParallel": false,
    "IgnoreDefaultRules": false,
    "CrawlArchives": false,
    "ExitCodeIsNumIssues": false,
    "BasePath": "",
    "AbsolutePaths": false,
    "RespectGitIgnore": false,
    "SkipExcerpts": false,
    "ConsoleVerbosityLevel": "Information",
    "DisableConsoleOutput": false,
    "LogFileLevel": "Error",
    "LogFilePath": null
}

Usage

devskim analyze -I path/to/src --options-json path/to/options.json

Custom Rules

To use custom rules, use the -r option to provide a comma separated list of either directories containing rule files, or individual rule files. To use only custom rules, you must specify --ignore-default-rules.

For languages that DevSkim does not natively support, you can add rules by providing custom languages.json and comments.json files. These files are always paired and must be provided together, or not at all.

Examples

# use default rules AND custom rules
devskim analyze /home/user/myproject -r /my/rules/directory -r /my/other/rules

# use only custom rules
devskim analyze /home/user/myproject -r /my/rules/directory -r /my/other/rules -i

# use custom languages and comments files
devskim analyze /home/user/myproject -r /my/rules/directory \
    --languages /my/rules/directory/languages.json --comments /my/rules/directory/comments.json

Custom Severity

To look only for issues with particular severity (e.g. critical, important, etc.), use the -s|--severity option.

Example

devskim analyze /home/user/myproject --severity critical,important

Output File and Format

DevSkim scan results can be stored in text, and sarif file formats. The default format is Sarif.

# Scan and output Sarif
devskim analyze -I /home/user/myproject results.sarif

# simple output to a file (text)
devskim analyze /home/user/myproject results.txt -f text

Custom Output Format

Text output format can be customized with the -o|--output-format switch.

Text

# Output file name and issue number 
devskim analyze /home/user/myproject results.txt -f text -o "%F [%R]"

# Output file name, line and column and issue name
devskim analyze /home/user/myproject results.txt -f text -o "%F:%L:%C - %N"

# Output into .csv file
devskim analyze /home/user/myproject results.csv -f text -o "%F,%L,%C,%R"

Exclude Files

Use the -g option to specify Glob patterns for identifying files to skip.

devskim analyze /home/user/myproject results.sarif -f sarif -g **/bin/**,**/obj/**,**/.git/**

Ignore Rules by ID

Use the --ignore-rule-ids option to specify exact IDs of DevSkim rules to ignore.

devskim analyze /home/user/myproject results.sarif -f sarif --ignore-rule-ids DS1234,DS5678