Skip to content

README.md

Latest commit

 

History

History
159 lines (125 loc) · 6.59 KB

README.md

File metadata and controls

159 lines (125 loc) · 6.59 KB

COBOL Scanner + Small Static Program Analysis

Summary

This repository contains a single-file COBOL security scanner and a small static program analysis (SPA) tool (control/dependency extraction). The scanner will:

  • Prefer an installed COBOL parser (legacylens_cobol_parser or cobol_parser) for AST-aware analysis.
  • Fall back to line-oriented regex heuristics if no parser is available.
  • Detect issues such as hardcoded credentials, dynamic SQL, file operations without FILE STATUS checks, string overflow risks, and unvalidated ACCEPT inputs.
  • Provide a simple SPA subcommand to produce control or dependency maps (output: python/json/dot).

Files

  • scanner.py
    • Main script: run security scans and small SPA operations.

Prerequisites

  • Python 3.7+ (Python 3.8/3.9/3.10/3.11/3.12+ recommended)
  • pip

Recommended: use a virtual environment.

Quick Setup (Windows PowerShell)

  1. Create a venv and activate it: py -3 -m venv venv .\venv\Scripts\Activate.ps1

  2. Upgrade pip (optional but recommended): python -m pip install --upgrade pip

  3. (Optional) Install an AST parser for better analysis:

    • Preferred package names (scanner will prefer legacylens_cobol_parser, then cobol_parser): python -m pip install legacylens_cobol_parser OR python -m pip install cobol_parser

    If you do not install either package, the scanner will still run using built-in regex heuristics.

Quick Setup (macOS / Linux)

  1. Create & activate venv: python3 -m venv venv source venv/bin/activate

  2. Upgrade pip: python -m pip install --upgrade pip

  3. (Optional) Install parser: python -m pip install legacylens_cobol_parser OR python -m pip install cobol_parser

How to run the scanner

  • Scan the current directory (recurses) with pretty output: python scanner.py scan .

  • Scan and use installed parser if available: python scanner.py scan . --use-legacylens

  • Scan single file: python scanner.py scan myprog.cbl --use-legacylens

  • Save JSON output: python scanner.py scan . --use-legacylens --format json > findings.json

  • Find files by extension (default): .cbl, .cob, .cpy, .cobol Include .txt files with: python scanner.py scan . --include-txt

Scanner output

  • Pretty output: grouped by severity with file:line, snippet, and remediation.
  • JSON output: list of findings. Each finding contains:
    • rule_id, title, severity (CRITICAL/HIGH/MEDIUM/LOW/INFO),
    • file, line, message, snippet, cwe, remediation

Tainting:

  • The scanner marks variables as "tainted" when it sees ACCEPT , RECEIVE ... INTO , or READ ... INTO . Tainted variables increase severity when used in dangerous operations (e.g., dynamic SQL).

SPA (Static Program Analysis) subcommand

The scanner includes a small SPA capability (control/dependency maps) for a single input file.

  • Control flow map (detects SECTION and PERFORM): python scanner.py spa -t control -f json -i myprog.cbl

  • Dependency (CALL) map: python scanner.py spa -t dep -f json -i myprog.cbl

  • DOT output (render with Graphviz): python scanner.py spa -t control -f dot -i myprog.cbl > myprog.dot dot -Tsvg myprog.dot -o myprog.svg

Notes about SPA

  • SPA is a lightweight, line-based heuristic. For accurate interprocedural analysis, use a full parser (LegacyLens/cobol_parser AST).

Troubleshooting

  1. "Could not import legacylens_cobol_parser" or parser missing:

    • The scanner tries (in order):
      1. legacylens_cobol_parser
      2. cobol_parser
    • If neither is found it uses regex heuristics.
    • To check availability in your active Python: python -c "import importlib; print(importlib.util.find_spec('legacylens_cobol_parser'), importlib.util.find_spec('cobol_parser'))"

  2. Module installed but scanner prints not found:

    • You may have multiple Python interpreters. Ensure you installed the parser into the same Python used to run scanner.py: python -m pip install cobol_parser python -c "import sys; print(sys.executable)"

  3. Permissions / encoding:

    • Files are read with encoding='utf-8', errors='ignore'. If you need another encoding adjust scanner.py read_file.

  4. False positives / negatives:

    • The built-in heuristics are conservative and line-based. For complex COBOL (copybooks, continuations, free/fixed format), install a parser (legacylens_cobol_parser/cobol_parser).

Interpreting common findings

  • COBOL-SECRET-001 (HIGH): Hardcoded credential (MOVE/VALUE of a literal into a variable with a credential-like name). Remediation: remove secrets, use secure storage.
  • COBOL-SQL-001 (HIGH): Dynamic SQL detected. Remediation: parameterize queries, validate input.
  • COBOL-SQL-002 (CRITICAL): Dynamic SQL using a tainted variable. Remediation: sanitize/validate input; consider prepared statements.
  • COBOL-FILE-001 (MEDIUM): File OPEN without FILE STATUS check. Remediation: define FILE STATUS and check results.
  • COBOL-STR-001 (MEDIUM): STRING/UNSTRING without ON OVERFLOW nearby. Remediation: add ON OVERFLOW handler.
  • COBOL-INPUT-001 (LOW): ACCEPT without nearby validation. Remediation: validate inputs.

Extending or customizing the scanner

  • Add/modify rules in analyze_security() in scanner.py.
  • Improve normalization for specific COBOL dialects by editing normalize_lines().
  • Add --exit-code flag to return non-zero for HIGH/CRITICAL findings (useful for CI).
  • Replace heuristics with AST-based checks using parser AST if available from LegacyLens.

Example workflow

  1. Create venv and install parser: py -3 -m venv venv .\venv\Scripts\Activate.ps1 python -m pip install cobol_parser

  2. Run scanner: python scanner.py scan . --use-legacylens --format json > results.json

  3. Open results.json, review HIGH/CRITICAL findings and use SPA to understand call/context: python scanner.py spa -t control -f dot -i suspicious.cbl > suspicious.dot dot -Tpng suspicious.dot -o suspicious.png

Security & Privacy

  • The scanner reads source files only and prints findings to stdout. If you redirect output to files be careful with sensitive contents.
  • Remove any hardcoded secrets from files before sharing publicly.

License & Attribution

  • This scanner is provided "as is" for analysis and demonstration. Adapt and integrate into your processes as you see fit.
  • It optionally integrates with LegacyLens/cobol_parser projects; please consult their licenses for redistribution/usage of those libraries.