COBOL linting with IBM ZCodeScan

IBM® ZCodeScan enables developers to scan COBOL applications for security vulnerabilities and perform code reviews across z/OS® applications.

ZCodeScan in Z Open Editor includes the following features:

• Security vulnerabilities scanner to identify potential issues in COBOL source code.
• Built-in rules file to easily set up the code reviews. These rules cover typical best practices in COBOL coding.
• Real-time code review with linting, which provides instant feedback on code quality within Z Open Editor.

IBM ZCodeScan is provided as part of IBM Developer for z/OS Enterprise Edition, which also includes a Command Line Interface (CLI) that enables code reviews to be run from anywhere for increased flexibility. For example, the CLI can be invoked from a developer’s workstation, a pipeline orchestrator, or any build framework. To learn more about the CLI, see the IBM Developer for z/OS documentation.

Currently, IBM ZCodeScan can scan only COBOL programs and copybook files that are free of syntax errors. See Known Issues for a complete list.

Running a code scan

Use any of the following methods to enable IBM ZCodeScan:

On-Demand IBM ZCodeScan: The On-Demand IBM ZCodeScan enables the developer to manually trigger the scan from the context menu.

1. Open a COBOL program file.

2. Right-click in the editor and select the menu item Execute IBM ZCodeScan.

3. Alternatively, open the VS Code Command Palette and select IBM Z Open Editor: Execute IBM ZCodeScan

Live IBM ZCodeScan: The Live IBM ZCodeScan feature dynamically scans the currently edited COBOL code. This feature is not enabled by default.

1. Open the User settings and go to IBM Z® Open Editor.

2. On the IBM Z Open Editor extension settings page, enable Cobol: Enable Live ZCode Scan.

Reviewing scan results

Issues identified by the scanner are presented through a linter-style interface, with squiggly underlines in the code and corresponding entries in the VS Code Problems View. These issues are highlighted based on the configurable severity of each rule.

• BLOCKER : Red
• HIGH : Red
• MEDIUM : Yellow
• LOW : Yellow
• INFO : Blue

If you hover over an issue in the editor, a Quick Fix menu appears, which offers the Learn more about the issue option. This opens a separate view beside the editor that displays the Rule Details document, as shown in the screenshot below.

You can also see the list of issues and details in the Problem View. Click the 💡 icon; then the Learn about the issue tab appears and opens the details view.

Managing rules

By default, all defined IBM ZCodeScan rules apply to the current VS Code workspace. The IBM Developer for z/OS documentation contains reference pages for rule management:

• See Defining Rules for the list of available rules.
• See Client Rule for details on how rules are configured.

If you do not want all predefined rules to be included in your scan, you can create a file named zcodescan-rules.yaml at the root level of your current VS Code workspace. The following is an example of a rules file. For detailed syntax, refer to the linked documentation.

rules:
  - id: codescan. cobol. rules.ProgramIdRule
    severity: INFO
  - id: zcodescan.cobol.rules.CallSyntaxRule
    severity: INFO
  - id: codescan. 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: codescan. cobol. rules.AcceptRule
  severity: INFO
  - id: codescan. cobol. rules. GotoRule severity: INFO
  - id: codescan. cobol. rules.GotoParagraphRule
  severity: MEDIUM
  - id: zcodescan.cobol. rules.UnprotectedAuthCredentialRule
  severity: HIGH
  - id: zcodescan.cobol.rules.BufferOverflowRule
  severity: INFO
  - id: codescan.cobol. rules.UninitialzedVariablesRule
  severity: MEDIUM
  - id: codescan.cobol. rules.AcceptDateTimeRule
  severity: MEDIUM
  - id: codescan. cobol. rules.SqlInjectionRule
  severity: INFO

You can also find this example in the Z Open Editor samples Git repository at https://github.com/IBM/zopeneditor-sample/blob/wazi-main/zcodescan-rules.yaml.

Note: VS Code multi-root workspaces are supported. Programs are scanned using the rules file located in the same workspace.

Editing rules files in VS Code

VS Code helps you edit rules files by providing code completion and documentation hovers for the YAML content, similar to how you use the editor for ZAPP files. This requires you to install the Red Hat YAML VS Code extension and also download and configure the schema file for rules files.

1. Install the YAML Language Support by Red Hat plugin to enable YAML syntax highlighting and schema validation in VS Code.

2. Click the gear icon ⚙️ in the Sidebar of the editor and select Settings.

3. Search for Yaml: Schemas and click Edit in settings.json to open the "settings.json" file.

4. You can see entries for the ZAPP and ZCodeFormat schema files already present in the user settings JSON. Just modify this section to look like this without changing the local path of the first two entries, which are specific to your user account:

   "yaml.schemas":
     {
       "file:///Users/user/.vscode/extensions/ibm.zopeneditor-5.5.0/resources/zapp-schema-1.4.0.json":
         ["zapp.yaml"],
       "file:///Users/phaumer/.vscode/extensions/ibm.zopeneditor-5.5.0/resources/zcodeformat-schema-0.0.1.json":
         ["zcodeformat.yaml"],
       "https://raw.githubusercontent.com/IBM/zopeneditor-about/refs/heads/main/zcodescan/zcodescan-rules-1.0.0.json":
         ["zcodescan-rules.yaml"]
     }
   

5. If you are working in an airgap configuration and cannot access the internet, you can ask your administrator to download the schema file from the URL above and provide it to you. You can then provide a local file URL instead, similar to the ZAPP example shown earlier.

6. After you configure the YAML VS Code extension with the schema, you open your rules file and test code completion by adding a file pattern to the schema. Here are some suggested file patterns you can use:

   

You can now see the schema validation active in configuration files. Use the autocomplete feature by pressing CTRL+Space to display options based on the current index context, or type a keyword and press TAB.