COBOL code analysis with IBM ZCodeScan

IBM® ZCodeScan is included with IBM Developer for z/OS® Enterprise Edition. This capability enables you to scan COBOL applications for security vulnerabilities and conduct code reviews across z/OS applications. IBM ZCodeScan provides:

Security vulnerabilities scanner to identify potential issues in COBOL source code.
A built-in rules file to easily set up the code reviews, covering typical COBOL best practices.
Real-time code review with linting, which provides instant feedback on code quality within IDE.

For more information, see IBM ZCodeScan Overview.

Note:

IBM ZCodeScan is only available as an MVP in IBM Developer for z/OS for eclipse.
IBM ZCodeScan can scan COBOL programs and copybook files only if they are free of syntax errors.

Before you begin

The following are required to run a COBOL code analysis:

Ensure that IBM Developer for z/OS is installed.
Ensure you have a COBOL file or a folder with COBOL files ready for analysis.

Running a code scan

IBM ZCodeScan provides an On-Demand scan to manually analyze your COBOL code. To run a scan, follow these steps:

Open your IDE and navigate to the file containing the COBOL code ready for analysis.
Open the file.
From the context menu, select IBM ZCodeScan.

Note: To exclude some predefined rules from your scan, create a file named zcodescan-rules.yaml at the root of your current IBM Developer for z/OS workspace.

Reviewing scan results

Issues identified by the scanner are presented through a linter-style interface, with squiggly underlines in the code and entries in the Problems view. Each issue is highlighted based on the configurable severity of its rule:

Severity	Color
BLOCKER	Red
HIGH	Red
MEDIUM	Yellow
LOW	Yellow
INFO	Blue

After running IBM ZCodeScan, you can review the issues and their details in the IDE. Follow these steps to see more information about an issue:

Locate the issue in the Problems view.
Right-click the issue and select Quick Fix from the context menu.
In the Quick Fix window, review the error message and click Finish.

A Detailed Description view opens, providing more information about the issue and guidance for resolving it.

Managing rules

By default, all defined IBM ZCodeScan rules apply to the current IBM Developer for z/OS workspace.

For detailed guidance and full syntax information on managing rules, see Defining Rules for a complete list of rules and Client Rule for configuration details.

The following is an example of a rules file. For detailed syntax, refer to the linked documentation.

rules:
  - id: zcodescan.cobol.rules.ProgramIdRule
    severity: INFO
  - id: zcodescan.cobol.rules.CallSyntaxRule
    severity: INFO
  - id: zcodescan.cobol.rules.SqlWhereRule
    severity: HIGH 
    statements:
      - name: "Select"
        value: true
      - name: "Delete"
        value: true
      - name: "Update"
        value: true
  - id: zcodescan.cobol.rules.RequireEndClauseRule
    severity: HIGH 
    statements:
      - name: "If" 
        value: true
      - name: "Evaluate"
        value: true
      - name: "Read"
        value: true
      - name: "Search"
        value: true
      - name: "Call"
        value: true
  - id: zcodescan.cobol.rules.AcceptRule
     severity: INFO
  - id: zcodescan.cobol.rules.GotoRule 
     severity: INFO
  - id: zcodescan.cobol.rules.GotoParagraphRule
     severity: MEDIUM
  - id: zcodescan.cobol.rules.UnprotectedAuthCredentialRule
     severity: HIGH
  - id: zcodescan.cobol.rules.BufferOverflowRule
     severity: INFO
  - id: zcodescan.cobol.rules.UninitialzedVariablesRule
     severity: MEDIUM
  - id: zcodescan.cobol.rules.AcceptDateTimeRule
     severity: MEDIUM
  - id: zcodescan.cobol.rules.SqlInjectionRule
     severity: INFO
  - id: zcodescan.cobol.rules.StopRunRule
     severity: MEDIUM
  - id: zcodescan.cobol.rules.EvaluateWhen0therRule
     severity: MEDIUM
  - id: zcodescan.cobol.rules.PerformWithoutThroughRule
     severity: MEDIUM
  - id: zcodescan.cobol.rules.PerformWithThroughRule
     severity: MEDIUM
 - id: zcodescan.cobol.rules.InitializeRule
     severity: MEDIUM
 - id: zcodescan.cobol.rules.EvaluateNotRule
     severity: MEDIUM

In IBM Developer for z/OS, you have the option to download the zcodescan-rules.yaml file by simply clicking on it. This feature allows you to access and review the defined rules for IBM ZCodeScan.

Editing rules files

You can configure IBM Developer for z/OS with the IBM ZCodeScan schema so that it can provide IntelliSense and code completion for the ZCodeScan-rules YAML file.

Open the IBM Developer for z/OS Preferences.
- In Windows, select Window > Preferences.
- In MacOS, select IBM Developer for z/OS > Settings.
Create a IBM ZCodeScan content type to detect if a file that you open is a IBM ZCodeScan YAML file to be validated. To do so, complete the following actions in the Preferences dialog:
1. Select General > Content types.
2. In the Content types panel, open Text > Wild Web Developer supported web dev file and select YAML.
3. Click the Add Child and enter IBM ZCodeScan configuration file in the Name input field to specify that this content type corresponds to the IBM ZCodeScan configuration file.
4. Click the Add associated with the File associations panel and specify file patterns that match the names of the IBM ZCodeScan YAML file you expect to edit. Then, if the path of the opened file matches at least one of these file patterns, the editor will begin validating its structure. You can use wildcard characters, a full or relative path, or simply a file name.
  For example, you can enter the **.yaml file pattern to specify that all the files with a yaml extension in the config folder are IBM ZCodeScan configuration files that are to be validated.
Create a schema association to link the IBM ZCodeScan file that match the content type to their respective schema so the file will be validated against them. To do so, complete the following actions in the Preferences dialog:
1. Open General > Schema associations.
2. Press Add to add a schema association.
3. Open the Content Type drop-down list and select the first content type that you created in the previous step: IBM ZCodeScan configuration file.
4. In Schema location, enter the following line and click OK:
  zcodescan-rules.json.
  
  This line links to the IBM® Public GitHub repository that hosts the schemas. Using a file path to reference a locally downloaded schema does not work at this time due to a bug in Wild Web Developer. You must be able to access this URL to use IBM ZCodeScan schemas in IBM Developer for z/OS.