Policy files
complydoc check holds a folder to rules written in YAML, and exits non-zero when
it fails them. The rules are the checks cd.expect
offers, so a policy file and a Python test ask the same questions.
complydoc check ./documents --policy policy.yamlversion: 1rules: no_hidden: severity: medium no_identifiers: severity: high readiness_at_least: score: 60 no_network: true all_categories_scanned: level: warning no_regressions: baseline: baseline.jsonEvery rule runs, so one run lists everything that failed rather than stopping at
the first. A rule with no parameters is written as true, and false switches one
off without deleting it. Packs for a finance, legal or HR folder are listed below.
| Rule | Parameters | Fails when |
|---|---|---|
no_identifiers |
severity, evidence, categories |
An identifier in text or metadata matches the filters |
no_hidden |
severity (default medium) |
A hidden or instruction-like passage is at or above it |
readiness_at_least |
score |
A document scores below it |
global_score_at_least |
score |
Global readiness is below it |
facts_found |
facts, threshold |
A loader misses a fact |
no_network |
none | A loader attempted or made a connection, or a registered classifier or --verify vision model sent document content to a host |
no_identifiers_sent |
severity |
A step of a pipeline recorded with cd.observe sent text holding an identifier at or above it to a host |
only_hosts |
hosts |
A step of a recorded pipeline reached a host not in the list |
no_failures |
none | A loader failed on a file, or a file was skipped |
all_categories_scanned |
none | An identifier category could not be scanned |
no_regressions |
baseline, score_tolerance |
Anything got worse than the baseline |
level: warning on any rule reports it without failing the gate; the default is
error. Relative paths, such as a baseline, are resolved from the policy file’s
own directory.
A finding that is not a problem, such as your own company’s account number, can be ignored with a reason. Every rule then skips it.
Exit codes
Section titled “Exit codes”| Code | Meaning |
|---|---|
| 0 | Every error rule passed. Warnings may still be reported |
| 1 | An error rule failed |
| 2 | The policy, the path or the report could not be read |
Output for CI
Section titled “Output for CI”complydoc check ./documents --policy policy.yaml \ --markdown check.md --sarif check.sarif--markdown writes a summary to post as a pull request comment: a table of every
rule and its result, then the failures under each rule that did not pass.
--sarif writes SARIF 2.1.0, which GitHub code scanning reads, with one result
per failure and the document it belongs to as its location. Both name documents
by their path from the working directory, which in CI is the repository root, so
code scanning links each result to its file.
On GitHub, the GitHub Action runs this, posts the summary on the pull request and uploads the SARIF.
To gate on a report that was already written, pass it instead of a path:
complydoc audit ./documents --out build --name current -qcomplydoc check --report build/current.json --policy policy.yamlFrom Python
Section titled “From Python”import complydoc as cdfrom complydoc.report.policy import check_policy, read_policy
report = cd.full_audit("./documents")result = check_policy(report, read_policy("policy.yaml"))print(result.passed, [rule.rule for rule in result.failed])cd.expect(report) remains the way to write these checks inside a test suite; a
policy file is for the teams and pipelines that would rather not.
Three policies ship with the package. Pass the name where a path would go. A path
to a YAML file is that file: copy a pack out, edit it, and point --policy at the copy.
complydoc check ./invoices --policy finance- uses: complydoc/complydoc@v0.7.5 with: path: documents policy: legal| Pack | For | Fails when |
|---|---|---|
finance |
Invoices, statements, tax filings | An IBAN, card number, bank detail or tax identifier is found. VAT numbers are filed at low severity, so the floor is low. Hidden text from medium. Readiness under 60 |
legal |
Contracts and filings | Hidden text or an instruction-like passage is found at any severity, or a national identity number is found |
hr |
Personnel files | A personal identity number, a name, a date of birth, an email or a phone number is found. Date of birth is the health-adjacent identifier |
Each pack also fails when a run opens a network connection or a file cannot be read,
and reports a category that could not be scanned as a warning. Names need a model;
the action guide says how to fetch one. The files are
src/complydoc/policies/ in the repository, and ship inside the package.