Skip to content

CUSTOMIZING.md

Latest commit

 

History

History
37 lines (22 loc) · 2.38 KB

CUSTOMIZING.md

File metadata and controls

37 lines (22 loc) · 2.38 KB
Raw

Customizing LedgerCast

LedgerCast is designed to be a template you can adapt for your own internal audit work. While the project models common SOX ITGC control categories (Access Management, Change Management, Backup & Recovery), the pattern easily generalizes to other control types (e.g., IT Operations, Job Scheduling, Password Configurations).

1. Adding a New Control Test

To add a new control test, follow this pattern:

  1. Create the Script: Copy the structure of an existing test (e.g., ledgercast/test_access_management.py).
  2. Define Metadata: Set your CONTROL_ID and CONTROL_OBJECTIVE constants at the top of the file.
  3. Write the Test Logic: In your run_test(data_dir) function, read your custom CSV, implement the logic to identify exceptions, and return a tuple of (population_size, list_of_exceptions).
  4. Wire it Up: Add your new script to the tests array inside ledgercast/run_all_tests.py so the ledgercast test command automatically picks it up.

2. Using Your Own Data

The ledgercast CLI is built to run against external datasets without editing the code. Simply point the CLI to a directory containing your CSVs using the --data-dir flag:

ledgercast test --data-dir /path/to/your/audit/data

Make sure your CSV files have the same required schemas (see data/README.md).

3. Updating the Risk & Control Matrix (RCM)

If you modify or add new controls, ensure you document them in the Risk & Control Matrix (docs/RCM.md). Maintain the existing markdown table structure:

| Control ID | Control Objective | Control Description | Test Procedure | Frequency | Risk Rating | Test Result |

4. Findings Architecture (CLI vs Dashboard)

LedgerCast maintains persistent state for all identified exceptions.

The authoritative store is data/findings_state.json. Any updates made via the ledgercast findings CLI commands are written directly to this file.

The dashboard copy is docs/sample-data/findings_state.json. Because the dashboard is hosted as a static site (e.g., GitHub Pages) from the docs/ directory, it cannot read files outside of its root. To solve this, ledgercast test automatically copies the latest authoritative store to the docs/sample-data/ folder at the end of every run.

Note: Treat docs/sample-data/findings_state.json purely as a read-only build artifact for the dashboard. Do not edit it directly.