Getting Started with IBM ZCodeScan on the Command Line Interface (CLI)

IBM® ZCodeScan is a command-line interface (CLI) tool designed to scan COBOL and PL/I source code for potential issues and vulnerabilities. This section provides information about how to install and use IBM ZCodeScan in CLI.

For details information about how to install IBM ZCodeScan CLI, see Installing IBM ZCodeScan on a distributed environment.

After installation, you can use IBM ZCodeScan command in your terminal. The basic commands is as follows:

usage: zcodescan [-h] [-sf sourceFolder [sourceFolder ...]] [-if includeFolder [includeFolder ...]] [-sfl sourceFilesList] [-ifl includeFilesList] [-se sourceExtensions [sourceExtensions ...]] [-ie includeExtensions [includeExtensions ...]]
                 [-sff sourcesFilterFile] [-e encoding] [-rf rulesFile] [-rfo rulesFolder [rulesFolder ...]] [-re rulesExtensions] -cf configFile [-of outputFile] [-off outputFileFormat] [-et exportType] [-erf exportRulesFile]
                 [-crdf customRulesDomainsFolder [customRulesDomainsFolder ...]] [-crde customRulesDomainsExtensions] [-crjf customRulesJarsFolder [customRulesJarsFolder ...]] [-yvt {strict,warning,skip}] [-ersf exportRulesSchemaFile] [-p]
                 [-lcf logConfigFile] [-fa] [-d] [-v] [-cb createBaseline] [-ab applyBaseline]

IBM ZCodeScan command:

options:
  -h, --help            show this help message and exit
  -sf, --sourceFolder sourceFolder [sourceFolder ...]
                        Provide the source folder(s) to scan
  -if, --includeFolder includeFolder [includeFolder ...]
                        Provide the include folder(s) (default: source folder(s))
  -sfl, --sourceFilesList sourceFilesList
                        Provide the source files list (one source per line)
  -ifl, --includeFilesList includeFilesList
                        Provide the include files list (one include per line)
  -se, --sourceExtensions sourceExtensions [sourceExtensions ...]
                        Source file(s) extension to search for (default: COBOL: .cbl, .cobol, .cob, .cob2 - PLI: .pl1, .pli)
  -ie, --includeExtensions includeExtensions [includeExtensions ...]
                        Include extension(s) to search for (default: COBOL: .copy, .cpy, .copybook, .cobcopy - PLI: .inc, .include, .plinc, .pcx, .pci)
  -sff, --sourcesFilterFile sourcesFilterFile
                        The sources filter file name
  -e, --encoding encoding
                        Provide the encoding of the source and include files (default: OS encoding)
  -rf, --rulesFile rulesFile
                        The YAML rule file to apply (default: run all applicable rules)
  -rfo, --rulesFolder rulesFolder [rulesFolder ...]
                        Rules folder to search for
  -re, --rulesExtensions rulesExtensions
                        Rules file extension(s) to search for (default: .yml, .yaml)
  -cf, --configFile configFile
                        The IBM ZCodeScan config file
  -of, --outputFile outputFile
                        The output file in YAML or JSON. See --outputType.
  -off, --outputFileFormat outputFileFormat
                        Output format: YAML or JSON. For better performance, JSON is highly recommended. (Default: YAML)
  -et, --exportType exportType
                        Types of export, separated by commas (only sonarqube and junit for now)
  -erf, --exportRulesFile exportRulesFile
                        The file to export all defined and applicable rules
  -crdf, --customRulesDomainsFolder customRulesDomainsFolder [customRulesDomainsFolder ...]
                        Custom rules domains folder to search for
  -crde, --customRulesDomainsExtensions customRulesDomainsExtensions
                        Custom rules domains extension(s) to search for (default: .yml, .yaml)
  -crjf, --customRulesJarsFolder customRulesJarsFolder [customRulesJarsFolder ...]
                        Custom rules Java '.jar' folder to search for
  -yvt, --yamlValidationType {strict,warning,skip}
                        Yaml schema compliance validation type for rules file (default: strict)
  -ersf, --exportRulesSchemaFile exportRulesSchemaFile
                        Export the rules schema with ZCodeScan predefined rules and Custom rules domains as JSON
  -p, --progress        Show progression
  -lcf, --logConfigFile logConfigFile
                        The logging configuration file (optional)
  -fa, --forceAnalyze   Force analyzing source(s) with error(s) (default: False)
  -d, --debug           Verbose output and logging
  -v, --version         Print product version and exit

Baseline Options:
  -cb, --createBaseline createBaseline
                        Capture known issues once, then track only what changes
  -ab, --applyBaseline applyBaseline
                        Apply baseline for Incremental scans

Exit Values
  0 - No issue found.
  1 - The highest issues severity found is INFO.
  2 - The highest issues severity found is LOW.
  3 - The highest issues severity found is MEDIUM.
  4 - The highest issues severity found is HIGH.
  5 - The highest issues severity found is BLOCKER.
 -1 - Scan error(s).

Important: Ensure that you define the following mandatory parameters:

Provide either a –sf or –sfl to define the sourceFolder or sourceFilesList respectively.
–cf for configFile.
–of for outputFile, which is YAML file.

After successful installation, you can now use IBM ZCodeScan command in your terminal. For more information about the CLI command, see Syntax of CLI Command.

IBM ZCodeScan CLI supports Baseline analysis to identify newly introduced issues while ignoring existing findings. For detailed setup and usage instructions, see IBM ZCodeScan Baseline management guide.

Examples

To scan a source folder named my_source_folder and generate an output file named output.yaml, use the following command:
```
zcodescan -sf my_source_folder -cf config.yml -of output.yaml
```

To export the results to a SonarQube JSON file, add

-et
sonarqube

zcodescan -sf sourceFolder -cf config.yml -of output.yml -et sonarqube

To generate a Junit XML file, add

-et
junit

zcodescan -sf sourceFolder -cf config.yml -of output.yml -et junit

For additional information, use the -h or –help option.