Code analysis with IBM ZCodeScan

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

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

For more information, see IBM ZCodeScan Overview.

Custom Rules: Helps you define organization-specific coding standards and best practices. Custom rule models enable you to extend ZCodeScan with domain-specific rules tailored to your development requirements. Custom rules must be defined in separate rule model files, such as rules-domains.yaml, and referenced in your ZAPP profile configuration. For more information, see the IBM ZCodeScan custom rules.

Note: IBM ZCodeScan can scan COBOL or PL/I programs and copybook files only if they are free of syntax errors.

Before you begin

The following are required to run a COBOL or PL/I code analysis:

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

Configuring ZCodeScan rules

ZCodeScan configuration can be managed through ZAPP profiles. You can define global rules and application-specific rule overrides using YAML files that are referenced in your zapp.yaml configuration.

Note: If a ZAPP profile is not configured for ZCodeScan, all predefined rules are applied.

Creating a ZAPP Profile for ZCodeScan

Create or update the zapp.yaml file at your workspace root and define a ZCodeScan profile with the following structure:

profiles:
  - name: zcodescan
    type: zcodescan
    settings:
      rules:
        - type: local
          locations:
            - "**/rules/zcodescan-${app-name}-rules.yaml"
            - "**/shared/zcodescan-${global-rule}/rules/global_rules.yaml"
      customRuleModels:
        - type: local
          locations:
            - "**/rules-domains/rules*domains.yaml"
      customRuleJars:
        - type: local
          locations:
            - "zcodescan/**/*.jar"
      baselines:
        - type: local
          locations:
            - "zcodescan/baseline.json"

Note: The locations property supports glob patterns, enabling you to target multiple YAML files with a single pattern. For example, you can use patterns such as "**/rules/zcodescan-${app-name}-rules.yaml" to match all rule files in the directory.

For more information about custom rules, see IBM ZCodeScan custom rules.

Global rules configuration

Define global rules in a file such as "**/shared/zcodescan-${global-rule}/rules/global_rules.yaml". This file contains standard rules with their default severities, which apply across the entire workspace.

Example structure:


rules:
  - id: zcodescan.cobol.rules.BinarySubscriptRule
    severity: LOW
  - id: zcodescan.cobol.rules.RequireEndClauseRule
    severity: HIGH
    statements:
      - name: "If"
        value: true
      - name: "Call"
        value: true
  - id: zcodescan.cobol.rules.UnprotectedAuthCredentialRule
    severity: LOW

Application-specific rule overrides
Create application-specific rules files, such as "**/rules/zcodescan-${app-name}-rules.yaml", to override global definitions for applications. This enables you to adjust rule severities or enable or disable specific rules. To override the global rules in the profile, ensure that this file is listed before the global rule file.
Example structure:
```
rules:
  - id: zcodescan.cobol.rules.BinarySubscriptRule
    severity: BLOCKER
  - id: zcodescan.cobol.rules.UnprotectedAuthCredentialRule
severity: OFF
```

Baseline management

IBM ZCodeScan supports baseline management to help you maintain code quality by tracking known issues and identifying new issues introduced during development. This feature enables development teams to establish quality gates without being overwhelmed by existing technical debt. By creating a baseline snapshot of your code’s current state, you can focus attention on new issues while maintaining visibility into known problems. Baseline management is particularly valuable in the following scenarios:

Legacy code modernization: When working with existing codebases that contain numerous quality issues, baselines allow you to prevent new issues from being introduced while gradually addressing existing ones.
Incremental quality improvement: Establish quality standards at specific milestones and ensure that no regressions occur as development continues.
CI/CD pipeline integration: Use baselines as quality gates that fail builds only when new issues are introduced, not because of pre-existing known issues.
Team onboarding: New team members can focus on writing quality code without being distracted by historical issues that they did not create.
Release management: Create baselines for each release to track quality improvements and prevent quality degradation between versions.
Compliance and audit trails: Maintain a historical record of code quality at key points in the development lifecycle.

Creating a Baseline

Baselines are currently created using the ZCodeScan CLI.

For complete CLI documentation on baseline management, see the IBM ZCodeScan Baseline Management Guide.

Configuring a Baseline in the Editor

Once you have created a baseline file, configure it in your ZAPP profile to enable baseline support in eclipse:

Open or create a zapp.yaml file in your workspace.

Add the baselines setting to your ZCodeScan profile.

profiles:
  - name: my-zcodescan-profile
    type: zcodescan
    settings:
      rules:
        - type: local
          locations:
            - "zcodescan/rules.yaml"
      baselines:
       - type: local
          locations:
            - "zcodescan/baseline.json"

Save the ZAPP file.

How baselines work in the editor

When a baseline is configured:

Known issues are suppressed: Issues that exist in the baseline file are not shown in the Problems view or highlighted in the editor.
New findings are displayed: Only issues introduced after the baseline was created are displayed, allowing you to focus on code changes.
Developer experience: The Problems view displays only new issues that require attention.

Running a code scan

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

Open your IDE and navigate to the file containing the COBOL or PL/I 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: 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

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. Currently, we need to configure two schema files: one for the Rule file and one for the Domain file. 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:
  Rules schema zcodescan-rules.json and Domain schema zcodescan-rules-domains.json.
  
  Note: 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.