self service guide

CryptoProof local self-service guide

First time using CryptoProof? Read the short Quick Start for the product purpose and first draft. This page is the detailed operating reference.

Early Access boundary: only the documented input subset is supported. Preflight can reject a workbook. Final vendor review is always required. The support policy draft covers product usage and reproducible bugs; CryptoProof staff do not fill customer questionnaires or repair arbitrary Excel files.

This guide is for a vendor's own security/product engineer. All commands run locally. CryptoProof does not scan source code, upload files, use an LLM, or contact its maintainer. Install the local wheel and its pinned dependencies as described in INSTALL_UPDATE_REMOVE.md, then run these commands from the extracted bundle folder with sample/ next to docs/. From a source checkout instead, set PYTHONPATH=src and replace sample/ with release-sample/.

Activate the dedicated virtual environment first, or replace each python below with that environment's python.exe path.

python -m cryptoproof --help

Privacy: Keep the input CBOM, original questionnaire, owner answer library, mapping file, draft directory and internal-evidence.json in a vendor-controlled directory. Do not paste sensitive organizational answers into a command line if shell history is retained; use --answer-file.

1. Preflight the original XLSX

python -m cryptoproof preflight --questionnaire sample/sample-questionnaire.xlsx --output preflight.json

Open preflight.json. It lists every sheet, candidate header rows, detected/effective columns, total question count, ignored_sheets, acknowledged_ignored_sheets, issue code, and self_service_fix. It does not print question/answer contents. The bundled sample initially reports MAPPING_REQUIRED because its nonempty Read me sheet is not yet acknowledged. Inspect every sheet and confirm the question count against the buyer's workbook. The verdict and exit code are:

compile repeats preflight and refuses to create output until an XLSX verdict is READY. Macro-enabled workbooks, external links, hidden sheets/rows/columns, protected question sheets, merged/formula/validated target cells, drawings, embedded controls, pivots, chart sheets and signature parts are outside the supported subset. A comments-only VML drawing is allowed; its text is screened for high-confidence secret patterns and must be reviewed by the vendor. Every nonempty sheet with no recognized question mapping requires an explicit acknowledgement, including sheets named Read me or Instructions. The tool does not remove protection or edit the original.

For the bundled synthetic sample, the supplied mapping file already acknowledges the unchanged Read me content. To make your own acknowledgement after opening and inspecting a non-question sheet:

python -m cryptoproof ignore --questionnaire customer.xlsx --sheet 'Instructions' --confirm-no-questions --output customer-map.json
python -m cryptoproof preflight --questionnaire customer.xlsx --mapping customer-map.json --output checked-preflight.json

Use --base-mapping existing-map.json when adding another ignored sheet. The acknowledgement stores a SHA-256 of that sheet's content, not its text. If the sheet changes, preflight stops again. Never use ignore for a sheet with customer questions.

2. Save a reusable column mapping

For an ambiguous customer workbook, select the actual question, answer and evidence lanes. The following command demonstrates a reusable explicit mapping for the sample's PQC Inventory sheet (18 questions, header row 5) while retaining its Read me acknowledgement. Its other question sheet remains automatically mapped:

python -m cryptoproof map --questionnaire sample/sample-questionnaire.xlsx --sheet 'PQC Inventory' --header-row 5 --id-col A --question-col C --answer-col D --evidence-col E --base-mapping sample/sample-mapping.json --output sample-map.json
python -m cryptoproof preflight --questionnaire sample/sample-questionnaire.xlsx --mapping sample-map.json --output mapped-preflight.json

Inspect each effective_mapping and its header_text in the second report. Use --base-mapping existing-map.json when adding another sheet to a saved configuration. A mapping file can be reused for the next questionnaire with the same sheet names, header rows and column layout. Rerun preflight for every new file; reuse is not permission to skip validation. The mapping JSON never stores questionnaire answers.

3. Store organizational answers with your own approval

CBOM facts cannot prove migration dates, internal owners, company policy, continuous monitoring or third-party assessments. An authorized vendor reviewer may add an answer to a local answer library. The entry carries scope, reviewer, approval date and expiry date. Use a UTF-8 answer file for sensitive or multiline text:

Set-Content -LiteralPath roadmap-answer.txt -Value 'A documented PQC migration roadmap exists.'
python -m cryptoproof library approve --file owner-answers.json --scope 'Synthetic Sample Product' --intent roadmap --answer-file roadmap-answer.txt --approved-by 'Synthetic Example Reviewer' --approved-on 2026-10-02 --valid-through 2027-10-02
python -m cryptoproof library list --file owner-answers.json

The example is fictional, not evidence of a real roadmap. Only an authorized vendor reviewer may approve an actual statement. --scope must exactly match the supplied CBOM's metadata.component.name; the sample uses Synthetic Sample Product. --intent is limited to roadmap, target_date, owner, continuous_monitoring, and third_party_assessment and matches a small canonical question set. The answer library accepts only documented organizational answer templates, including Target PQC migration date: YYYY-MM-DD. and PQC migration owner: Name.. Exact-question matching is also limited to approved organizational wording; arbitrary company text and technical/certification claims are rejected. Enter unsupported organization answers manually during review. Revoke a stale entry with python -m cryptoproof library revoke --file owner-answers.json --entry-id LIB-..., then approve a replacement. Library assertions become OWNER_APPROVED, never CBOM VERIFIED, and expire or stop matching under a different product scope.

4. Compile a draft

python -m cryptoproof compile --cbom sample/sample-product.cdx.json --questionnaire sample/sample-questionnaire.xlsx --mapping sample-map.json --output answered-customer.xlsx

The original questionnaire is untouched. answered-customer.xlsx is a draft copy. Its sibling answered-customer-cryptoproof/ contains draft-evidence-pack.zip, review-required.json, review-template.json, the evidence manifest, redacted customer CBOM, internal evidence mapping, and reports. No submission ZIP is produced by compile. A source cell with any existing value remains unchanged. UNKNOWN and OWNER_INPUT_REQUIRED remain unfilled. To reuse your approved answer library in a real run, add --answer-library owner-answers.json --scope 'Your exact product scope' --as-of YYYY-MM-DD; the explicit date controls validity and repeatability.

Review status meanings:

5. Review every row and finalize

Open the draft XLSX, review-required.json, evidence-manifest.json and review-template.json. In a copy of review-template.json, set every decisions value:

• approve for a generated VERIFIED, PARTIAL or OWNER_APPROVED answer that you have checked.
• approve_existing where write_action is existing_content_preserved; inspect that customer/vendor prefilled cell yourself, regardless of the compiler status.
• leave_unresolved for a blank UNKNOWN or OWNER_INPUT_REQUIRED row you intentionally leave unanswered.

Example fragment (the real file contains every question ID and the draft fingerprint):

{
  "version": 1,
  "draft_id": "COPY THE VALUE ALREADY IN review-template.json",
  "decisions": {"P-01": "approve", "P-07": "leave_unresolved"}
}

Do not delete other question IDs. finalize requires a decision for every row and checks every public draft file against its recorded SHA-256 digest:

python -m cryptoproof finalize --draft answered-customer-cryptoproof --decisions reviewed-decisions.json --output approved-evidence-pack.zip --approved-by 'Synthetic Example Reviewer' --approved-on 2026-10-02

The final ZIP contains the reviewed workbook, evidence artifacts and approval-record.json. It excludes internal-evidence.json. A changed public draft or changed original CBOM, questionnaire, optional old CBOM or answer library is rejected; rerun compile and review the new draft. The command also refuses to overwrite an existing final ZIP. For real use, supply the actual reviewer and review date. Approval records the vendor's review, not certification, legal compliance or CBOM completeness. Unresolved rows may remain blank if the vendor decides to submit them that way.

6. If a workbook is rejected

Read the self_service_fix in preflight. Make changes only in a new local workbook copy and rerun preflight. For macros, linked files, drawings, controls, pivots or chart sheets, request a plain XLSX version from the questionnaire sender if you cannot safely make one. For protected sheets, ask the workbook owner for an unlocked copy. For merged, formula or validated answer/evidence cells, choose dedicated free-text columns or request a simpler form. For ambiguous columns, use map and inspect effective_mapping. CryptoProof does not offer bespoke repair of unsupported templates; completing that questionnaire manually is the fallback.