Evaluate Parmana

The shortest path from a fresh clone to a working local system, and what to read next.

Evaluation only. Reading, building and running Parmana to assess it is permitted. Any other use needs a separate written agreement with Parmana Systems. See License and evaluation.

This page is for anyone assessing Parmana: an engineer trying it, a security reviewer, or an auditor. It needs no accounts, credentials, database or network access beyond npm ci. Auditors should continue with the Audit guide after step 3.

Requirements

• Node.js 24.6 or later. The hybrid Ed25519 and ML-DSA-65 signatures use node:crypto, which supports ML-DSA from 24.6.
• npm, as bundled with Node.js.
• Git, and Bash for two tests that syntax check shell scripts. On Windows, Git for Windows provides it.
• Docker, only for the optional offline check in step 5.

Linux, macOS and Windows are supported. On Windows PowerShell 5.1, run each command on its own line: it does not accept && between commands.

1. Install, build and test

git clone https://github.com/pavancharak/parmana.git
cd parmana
npm ci
npm run build
npm test

npm run build comes first because tests import the workspace packages from their built dist/ output; npm test refuses to run against stale output.

No .env is needed. The test setup uses the same local defaults as CI: the committed ./policies, in memory storage, and local Ed25519 keys generated for the run. Suites that need live services (HubSpot, Supabase) skip. Expect about 2,880 passing tests and about 54 skipped.

2. Run every example

npm run examples

This runs each tutorial in examples/tutorials/ against local mock connectors, with throwaway keys deleted afterwards. Several tutorials print FAILED or ✗ on purpose: they show a forged, replayed or tampered request being refused. The run ends with All Parmana examples completed successfully. and exit code 0.

To see the whole chain in one walkthrough (policy evaluation, signed authorization, envelope verification, credential isolation, connector execution and the signed Trust Record):

npx tsx examples/tutorials/60-end-to-end-enterprise-execution/run.ts

npm run preflight runs everything a contributor runs before a change: typecheck, lint, format check, the Python model check, every test, the build and every example.

3. Run the attack scenarios

npm run evaluate

This runs 16 attacks against the code and reports, for each one, whether it was blocked. Each scenario in evaluations/scenarios.json states what the attacker controls, the attack, the invariant that must hold, the claims it supports and the test files that check it.

ID	Attack	Claims
EV-01	Replay a used authorization	2.8, 2.10
EV-02	Forge or alter an authorization	2.8, 2.10, 2.15
EV-03	Use an expired authorization or a revoked key	2.10, 2.28
EV-04	Act without a person’s signed approval	2.42, 2.44, 2.47
EV-05	Forge or misuse an approval	2.42
EV-06	Declare one action, execute another	2.44
EV-07	Have an action judged by a weaker policy	2.22, 2.36
EV-08	Execute under an outdated policy version	2.27
EV-09	Rely on facts that changed after approval	2.29
EV-10	Obtain a connector’s credentials	2.23, 3.10, 3.17
EV-11	Reach a connector without going through the gateway	3.1
EV-12	Act without credentials or outside a caller’s scope	2.16, 3.16
EV-13	Change a policy without a second person	2.26, 2.34
EV-14	Alter a signed record after the fact	2.5, 2.6, 3.11
EV-15	Run the same transaction twice by racing	2.20
EV-16	Read or write a policy file outside the policy directory	none

To run only some scenarios, name them: npm run evaluate -- EV-04 EV-05. The Claims and evidence page gives the command for each claim.

The output ends with 16 of 16 attacks blocked. A scenario is BLOCKED when every test in its files passes, FAILED when any fails, and NOT RUN when a file is missing or ran nothing. The command exits non-zero unless all are BLOCKED.

It also writes evaluation-report.json: the commit, whether the working tree was clean, the Node.js version, a hash of the policies, and for each scenario its result and each test file’s SHA-256 and counts. Attach it to a review to show exactly what was run.

EV-04 covers prompt injection by its effect, not by detecting it: whatever an injected agent sends, an action is not authorized without a signed approval from a trusted person. These are tests of the code in the repository, run locally. They do not test a deployment’s configuration, its key custody or its network; the Audit guide covers those assumptions.

4. Try the hosted sandbox (optional)

A public sandbox runs the same API with demo policies and a published demo approver key. Use the Playground, or the scripts in examples/sandbox-playground/ from cURL, PowerShell, TypeScript or Python. See Live API and demos.

5. Run the full stack with no internet route (optional, Docker)

bash docker/local/offline-check/run.sh

This starts the server, Postgres and a stand in downstream system on a Docker network with no route to the internet, approves a policy through maker checker, runs an approved and a refused refund, and verifies the resulting Trust Record with only the public keys. See Offline verification. CI runs the same check on every change to the server image.

6. Verify a record without Parmana

Every approved action produces a signed Execution Trust Record. It can be checked with only the record and the public keys. The quickest way is Verify a record in your browser: paste a record and a key, nothing is uploaded. For scripts, use @parmana/sign (Apache 2.0, a separate repository) or this repository’s scripts/verify-trust-record.ts:

npx tsx scripts/verify-trust-record.ts trust-record.json default=default.public.pem

See Verify independently.

What to read next

If you want to	Read
Check what Parmana claims, and the evidence	Claims and evidence
See every threat, control and residual risk	Threat model
Try to break it	Security challenge
Review it for security or audit	Audit guide
Know what it does not do	Limitations
Understand the design	Architecture, then How Parmana thinks
Read the code chapter by chapter	The Parmana Handbook
See every gap found and how it was closed	docs/VERIFICATION-GAPS.md

Questions and feedback

Email [e-mail] for questions, a guided walkthrough or licensing. Report security issues privately as described in SECURITY.md.