Supply Chain Audit Agent

Audit prototype for VC-based supply-chain evidence.

Current implementation:

• Flask backend for audit execution and stored reports
• React frontend for running and inspecting audits
• Deterministic technical, compliance, certification, and ESG checks over a provenance graph built from a root VC CID
• One Docker-based review setup
• One supported script for generating a fresh VC-DAG test case

Reference notes:

• .codebase/REPOSITORY_MAP.md
• .codebase/ARCHITECTURE.md
• .codebase/INTEGRATIONS.md
• docs/current/01-end-to-end-flow.md
• docs/current/02-backend-runtime-flow.md
• docs/current/03-frontend-runtime-flow.md

Prerequisites

• Docker 24+
• Git
• A backend/.env file created from backend/.env.example

For running the existing implementation, the backend env file should be filled with real values. For generating a new test case, the same env file must also contain working Sepolia, Pinata, and wallet settings.

1) Clone

git clone git@github.com:ladylyly/audit-aiagents.git
cd audit-aiagents

2) Create the backend env file

cp backend/.env.example backend/.env

Then fill backend/.env.

Important fields for running the implementation:

• OPENAI_API_KEY
• RPC_HTTPS_URL
• CHAIN_ID
• PINATA_JWT
• PINATA_GATEWAY

OpenAI key usage:

• OPENAI_API_KEY is required. It is the primary key used by the backend LLM client for orchestration, report Q&A, explanation generation, and domain summaries.

For PINATA_GATEWAY:

• if you have your own dedicated Pinata gateway, use that
• otherwise use the public fallback: https://gateway.pinata.cloud

Example:

PINATA_GATEWAY=https://your-subdomain.mypinata.cloud

Fallback:

PINATA_GATEWAY=https://gateway.pinata.cloud

Additional fields needed for generating a new test case:

• DEPLOYER_PRIVATE_KEY
• ISSUER_PRIVATE_KEY
• PRODUCT_IMPLEMENTATION_ADDRESS
• PRODUCT_FACTORY_ADDRESS

3) Start the implementation

docker compose up --build

Then open:

• http://localhost:8080 for the frontend
• http://localhost:7002/api/health for the backend health check

To stop the stack later:

docker compose down

4) Run audits with existing root CIDs

After the frontend opens, paste a root VC CID into the input field.

Recommended test cases:

• best_case — expected high-quality reference case

QmZ5VLpJ81NMY6pa8L8WF4qhiaLCpPeVTeG329kBCy5Lih

• baseline_5_10vc — medium-sized baseline with 10 VCs

QmT8S9Bt6cmQXFhKpZmKkFvMyzj2g4hE9uqYGWDRUyX95n

• middle_case — mixed findings and partial compliance

Qmde4spA2QghViUw6sxvEr9WWe6hx4bJddtHLDooxsN8H1

• worst_case — expected heavy technical/compliance failure profile

QmNcd26F3c8zaXvtWHLqZLhx4EBNVSjfd7N5Q83gcyyJBi

• compliance_agent — compliance-heavy 25-VC case

QmXm7LhnpPL1NPayGabBcFuAqMytnNuzGSwQubTtUzcYAP

Additional optional cases:

• baseline_4_5vc — small smoke test

QmTzUsrV1djigGovmQNRjvic4ABqhHBiYV4TPTJMgxN4ah

• no_certification_info_20vc — certification-light / missing-certification scenario

QmZVLziFxJoRZNAiNJcHS5gNGeHLMvk9915qY6Gkk32CSg

Expected flow:

1. Paste the root CID into Root VC CID.
2. Start the audit run.
3. Wait until the report status changes from running to done.
4. Inspect the technical, compliance, certification, and ESG sections in the report.

Generated audit reports are stored in:

data/reports/

5) Generate your own test case

This repository keeps one supported generator path:

docker compose exec backend node backend/integrations/technical_verifier_tools/generate_publish_vc_dag.mjs

This command runs inside the backend container and creates one fresh VC-DAG test case with 25 VCs.

The generator writes its outputs to:

• data/generated/generated_vc_dag/<run-id>/manifest.json
• data/generated/generated_vc_dag/<run-id>/ephemeral_wallets.json

The new root CID is printed in the terminal as:

ROOT_CID=...

Use that new root CID in the frontend the same way as the existing one.

6) What is needed before generating a new case

The generator needs:

• a working Sepolia RPC endpoint
• a valid Pinata JWT
• a funded deployer wallet
• an issuer wallet
• deployed product clone information

In practice, that means these parts must already be configured:

• backend/.env
• contracts/deploy_stack/output/product_clones.json

Supplier and test wallets do not need to be configured manually. They are generated by the script and written to ephemeral_wallets.json.

7) Product clones and Sepolia ETH

The generator does not create product clones by itself. It reads them from:

contracts/deploy_stack/output/product_clones.json

Important:

• the generator needs at least 25 clone entries
• it always uses the last 25 entries in product_clones.json
• clones that were already used in earlier runs may already be in a later on-chain phase
• such reused clones can cause the automatic anchor step to fail

So the safe procedure is:

• create 25 fresh clones before generating a new case

ETH requirement:

• each clone locks 0.01 ETH
• 25 fresh clones therefore require 0.25 ETH plus Sepolia gas

If the deployer wallet has less than that, fresh-case generation should be postponed until the wallet is funded.

8) Create 25 fresh product clones

If you only want to audit an existing CID, you can skip this section.

8.1 Prepare the Truffle deployment env

From the repository root:

cd contracts/deploy_stack
./scripts_sync_from_agent_env.sh

This creates contracts/deploy_stack/.env.truffle from the values already stored in backend/.env.

8.2 Install deploy-stack dependencies

npm ci

8.3 Make sure the factory exists

If backend/.env already contains a valid PRODUCT_FACTORY_ADDRESS, this step can be skipped.

Otherwise deploy the Sepolia contract stack:

npm run deploy:sepolia

Then copy the printed addresses into backend/.env:

• PRODUCT_IMPLEMENTATION_ADDRESS
• PRODUCT_FACTORY_ADDRESS

8.4 Create 25 fresh clones

Still inside contracts/deploy_stack, run:

PRODUCT_FACTORY_ADDRESS=$(grep '^PRODUCT_FACTORY_ADDRESS=' ../../backend/.env | cut -d'=' -f2-) CLONE_COUNT=25 npx truffle exec scripts/create_product_clone.js --network sepolia

This appends 25 new clone entries to:

contracts/deploy_stack/output/product_clones.json

The generator will then use these fresh entries because it always takes the last 25 rows in the file.

9) Generate the fresh case

After the 25 fresh clones exist, go back to the repository root and run:

cd ../..
docker compose exec backend node backend/integrations/technical_verifier_tools/generate_publish_vc_dag.mjs

The command prints:

• ROOT_CID=...
• MANIFEST=...
• EPHEMERAL_WALLETS=...

Use the new ROOT_CID in the frontend audit input.

Notes

• This repository is set up for Docker-first use. No separate local Python, Node, or Rust installation is required for the normal review flow.
• For fresh-case generation, the Truffle deploy stack does require local Node.js because the Sepolia clone creation step is run from contracts/deploy_stack/.
• backend/.env is intentionally untracked and should stay local.
• If port 8080 or 7002 is already in use on your machine, stop the conflicting process before starting the stack.