Skip to content

Commit 6dd79a4

Browse files
ledwards2225ledwards2225
committed
chore: update audit tracking headers (#19295)
Improved audit status tracking - Updates all `AUDIT STATUS` headers - Moves all existing scope docs to dir audit/audit_scopes - Adds additional scope docs so that all files to be audited are now accounted for (marked with `status: Planned`) Running `python3 generate_audit_summary.py --status "not started` gives a list of files from each dir that have neither been audited or "planned" (placed into a scope doc). Latter can be viewed using `--status "planned``
1 parent c83279e commit 6dd79a4

File tree

621 files changed

+3789
-2025
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

621 files changed

+3789
-2025
lines changed

‎barretenberg/cpp/scripts/audit/README.txt‎

Lines changed: 55 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -10,19 +10,19 @@ HOW IT WORKS
1010
Each file being audited includes a structured comment block with audit status for multiple roles, e.g.:
1111

1212
// === AUDIT STATUS ===
13-
// internal: { status: not started, auditors: [], date: YYYY-MM-DD }
14-
// external_1: { status: not started, auditors: [], date: YYYY-MM-DD }
15-
// external_2: { status: not started, auditors: [], date: YYYY-MM-DD }
13+
// internal: { status: not started, auditors: [], commit: }
14+
// external_1: { status: not started, auditors: [], commit: }
15+
// external_2: { status: not started, auditors: [], commit: }
1616
// =====================
1717

1818
The script generate_audit_status_headers.sh populates all source files (in included dirs) with this header, unless one is already present.
1919

2020
2. The header in each file should be manually updated when the audit status changes, e.g.:
2121

2222
// === AUDIT STATUS ===
23-
// internal: { status: complete, auditors: [luke], date: 2025-04-17 }
24-
// external_1: { status: not started, auditors: [], date: YYYY-MM-DD }
25-
// external_2: { status: not started, auditors: [], date: YYYY-MM-DD }
23+
// internal: { status: Complete, auditors: [Luke], commit: abc123def }
24+
// external_1: { status: not started, auditors: [], commit: }
25+
// external_2: { status: not started, auditors: [], commit: }
2626
// =====================
2727

2828
3. Summary generation
@@ -31,8 +31,37 @@ HOW IT WORKS
3131
4. Dashboard visualization
3232
A static HTML file (audit_dashboard.html) visualizes the JSON using pie charts, with one chart per audit role per module. A summary section at the top gives a full-repo overview.
3333

34-
USAGE
35-
-----
34+
35+
CLI USAGE
36+
---------
37+
38+
The Python script supports multiple modes:
39+
40+
# Generate audit_summary.json (default)
41+
python3 generate_audit_summary.py
42+
43+
# List files with incomplete internal audit
44+
python3 generate_audit_summary.py --list-unaudited
45+
46+
# List files with incomplete audit, filtered by directory
47+
python3 generate_audit_summary.py --list-unaudited --dir chonk
48+
python3 generate_audit_summary.py --list-unaudited --dir stdlib/primitives
49+
50+
# List files without any audit headers
51+
python3 generate_audit_summary.py --list-missing
52+
53+
# List files with complete internal audit
54+
python3 generate_audit_summary.py --list-complete
55+
56+
# Check a different audit role (default: internal)
57+
python3 generate_audit_summary.py --list-unaudited --role external_1
58+
59+
# Output as JSON instead of human-readable
60+
python3 generate_audit_summary.py --list-unaudited --json
61+
62+
63+
DASHBOARD USAGE
64+
---------------
3665

3766
1. Run the server on the remote machine:
3867

@@ -45,3 +74,21 @@ USAGE
4574
3. View the dashboard in your browser:
4675

4776
http://localhost:8080/audit_dashboard.html
77+
78+
79+
QUICK EXAMPLES
80+
--------------
81+
82+
# See what needs auditing in stdlib
83+
python3 generate_audit_summary.py --list-unaudited --dir stdlib
84+
85+
# See which files are missing headers entirely
86+
python3 generate_audit_summary.py --list-missing
87+
88+
# Quick stats
89+
python3 generate_audit_summary.py
90+
# Output:
91+
# Total files with headers: 551
92+
# Internal audit complete: 172
93+
# Internal audit pending: 379
94+
# Files missing headers: 1103

‎barretenberg/cpp/scripts/audit/audit_scopes/aes128_audit_scope.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# External Audit Scope: aes128
2+
3+
Repository: https://github.com/AztecProtocol/aztec-packages
4+
Commit hash: TBD (link)
5+
6+
## Files to Audit
7+
Note: Paths relative to `aztec-packages/barretenberg/cpp/src/barretenberg`
8+
9+
### Native AES-128 Implementation
10+
1. `crypto/aes128/aes128.cpp`
11+
2. `crypto/aes128/aes128.hpp`
12+
3. `crypto/aes128/c_bind.cpp`
13+
4. `crypto/aes128/c_bind.hpp`
14+
15+
### Circuit-Friendly AES-128 Implementation
16+
5. `stdlib/encryption/aes128/aes128.cpp`
17+
6. `stdlib/encryption/aes128/aes128.hpp`
18+
19+
### ACIR Integration
20+
7. `dsl/acir_format/aes128_constraint.cpp`
21+
8. `dsl/acir_format/aes128_constraint.hpp`
22+
23+
### Lookup Tables
24+
9. `stdlib_circuit_builders/plookup_tables/aes128.hpp`
25+
26+
## Summary of Module
27+
28+
The `aes128` module provides both native and circuit-friendly implementations of the AES-128 block cipher with CBC (Cipher Block Chaining) mode. The native implementation in `crypto/aes128` provides standard AES-128 encryption/decryption for general use, including C bindings for external interfaces. The circuit-friendly implementation in `stdlib/encryption/aes128` enables AES-128 encryption to be proven inside arithmetic circuits using lookup tables to represent the S-box operations efficiently. The ACIR format integration allows AES-128 constraints to be specified in Noir programs, and the plookup tables module provides the lookup table definitions needed for efficient in-circuit S-box lookups.
29+
30+
## Test Files
31+
1. `crypto/aes128/aes128.test.cpp`
32+
2. `stdlib/encryption/aes128/aes128.test.cpp`
33+
34+
## Security Mechanisms
35+
None identified.

‎barretenberg/cpp/scripts/audit/audit_scopes/avm_recursive_verifier_audit_scope.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
# External Audit Scope: avm_recursive_verifier
2+
3+
Repository: https://github.com/AztecProtocol/aztec-packages
4+
Commit hash: TBD (link)
5+
6+
## Files to Audit
7+
Note: Paths relative to `aztec-packages/barretenberg/cpp/src/barretenberg`
8+
9+
### AVM Recursive Verifier Core
10+
1. `vm2/constraining/recursion/recursive_verifier.hpp`
11+
2. `vm2/constraining/recursion/recursive_verifier.cpp`
12+
3. `vm2/constraining/recursion/recursive_flavor.hpp`
13+
4. `vm2/constraining/recursion/recursive_flavor_settings.hpp`
14+
5. `vm2/constraining/recursion/goblin_avm_recursive_verifier.hpp`
15+
16+
### Flavor Definitions
17+
6. `flavor/mega_avm_flavor.hpp`
18+
7. `flavor/mega_avm_recursive_flavor.hpp`
19+
20+
### ACIR Integration
21+
8. `vm2/dsl/avm2_recursion_constraint.hpp`
22+
9. `vm2/dsl/avm2_recursion_constraint.cpp`
23+
10. `dsl/acir_format/avm2_recursion_constraint.hpp`
24+
25+
## Summary of Module
26+
27+
The AVM recursive verifier implements in-circuit verification of AVM2 proofs using two-layer recursive composition for efficiency. The core recursive verifier (AvmRecursiveVerifier) performs Mega-arithmetized verification of AVM2 proofs with a fixed verification key, implementing sumcheck verification, public input validation through multilinear evaluation, and Shplemini batch opening. The Goblin-based recursive verifier (AvmGoblinRecursiveVerifier) provides a two-phase approach: an inner Mega circuit recursively verifies the AVM2 proof and produces a MegaHonk proof plus Goblin proof (ECCVM, Translator, Merge), then an outer Ultra circuit verifies both proofs with hash-based consistency checks to ensure proper transfer of verifier inputs between layers. The recursive flavor definitions configure the circuit builder, curve operations (bn254), and commitment scheme (KZG) for the Mega-arithmetized recursive verifier. The ACIR integration layer (avm2_recursion_constraint) provides the interface for Noir programs to trigger AVM2 recursive verification, handling proof deserialization and witness generation for integration with the Ultra circuit builder.
28+
29+
## Test Files
30+
1. `vm2/constraining/recursion/recursive_verifier.test.cpp`
31+
2. `vm2/dsl/avm2_recursion_constraint.test.cpp`
32+
33+
## Security Mechanisms

‎barretenberg/cpp/scripts/audit/audit_scopes/avm_utils_audit_scope.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# External Audit Scope: AVM Utils
2+
3+
Repository: https://github.com/AztecProtocol/aztec-packages
4+
Commit hash: TBD
5+
6+
## Files to Audit
7+
8+
### Generic Relations
9+
1. `barretenberg/cpp/src/barretenberg/relations/generic_lookup/generic_lookup_relation.hpp`
10+
2. `barretenberg/cpp/src/barretenberg/relations/generic_permutation/generic_permutation_relation.hpp`
11+
12+
## Brief Summary of Module
13+
14+
Utility relations used by the AVM (Aztec Virtual Machine) for generic lookup and permutation operations.
15+
16+
## Test Files
17+
18+
TBD
19+
20+
## Security Mechanisms
21+
22+
TBD

‎barretenberg/cpp/scripts/audit/audit_scopes/biggroup_audit_scope.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
# External Audit Scope: Biggroup
2+
3+
Repository: https://github.com/AztecProtocol/aztec-packages
4+
Commit hash: [553c5eb82901955c638b943065acd3e47fc918c0](https://github.com/AztecProtocol/aztec-packages/tree/553c5eb82901955c638b943065acd3e47fc918c0)
5+
6+
## Files to Audit
7+
8+
The following files are to be audited, located in the `stdlib/primitives/biggroup` module (in no particular order):
9+
10+
1. `stdlib/primitives/biggroup/biggroup.hpp`
11+
2. `stdlib/primitives/biggroup/biggroup_impl.hpp`
12+
3. `stdlib/primitives/biggroup/biggroup_nafs.hpp`
13+
4. `stdlib/primitives/biggroup/biggroup_tables.hpp`
14+
5. `stdlib/primitives/biggroup/biggroup_secp256k1.hpp`
15+
6. `stdlib/primitives/biggroup/biggroup_edgecase_handling.hpp`
16+
17+
Update: Fixed lookup tables are implemented in `stdlib_circuit_builders/plookup_tables/non_native_group_generator.cpp` which must be added to the scope.
18+
19+
7. `stdlib_circuit_builders/plookup_tables/non_native_group_generator.cpp`
20+
8. `stdlib_circuit_builders/plookup_tables/non_native_group_generator.hpp`
21+
22+
## Brief Summary of Module
23+
24+
The biggroup module implements elliptic-curve operations using UltraHonk arithmetisation in barretenberg. This is specifically implemented to work for three curves[^1]: bn254, secp256k1 and secp256r1.
25+
26+
Please refer to the [biggroup README](https://github.com/AztecProtocol/aztec-packages/blob/553c5eb82901955c638b943065acd3e47fc918c0/barretenberg/cpp/src/barretenberg/stdlib/primitives/biggroup/README.md) for details on the specification and implementation details.[^2]
27+
28+
## Test Files
29+
1. `stdlib/primitives/biggroup/biggroup.test.cpp`
30+
2. `stdlib/primitives/biggroup/biggroup_secp256k1.test.cpp`
31+
32+
33+
34+
[^1]: Our implementation can _technically_ work for other curves as well (so long as the base and scalar fields of the curve can be represented with our bigfield module) but we have not tested it for other curves.
35+
36+
[^2]: The README uses Latex notation which doesn't render well on Github, you might need to use Markdown preview in VS code to render the file.

‎barretenberg/cpp/scripts/audit/audit_scopes/blake2s_blake3_audit_scope.md‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
# BLAKE2s + BLAKE3 Audit Scope
2+
3+
Repository: https://github.com/AztecProtocol/aztec-packages
4+
Commit hash: 4a956ceb179c2fe855e4f1fd78f2594e7fc3f5ea
5+
6+
### Files to audit
7+
8+
#### Native implementation
9+
1. ```barretenberg/cpp/src/barretenberg/crypto/blake2s/blake2s.hpp```
10+
2. ```barretenberg/cpp/src/barretenberg/crypto/blake2s/blake2s.cpp```
11+
3. ```barretenberg/cpp/src/barretenberg/crypto/blake2s/blake2-impl.hpp```
12+
4. ```barretenberg/cpp/src/barretenberg/crypto/blake3s/blake3s.hpp```
13+
5. ```barretenberg/cpp/src/barretenberg/crypto/blake3s/blake3s.tcc```
14+
6. ```barretenberg/cpp/src/barretenberg/crypto/blake3s/blake3-impl.hpp```
15+
16+
#### Stdlib circuit implementation
17+
18+
7. ```barretenberg/cpp/src/barretenberg/stdlib/hash/blake2s/blake2s.hpp```
19+
8. ```barretenberg/cpp/src/barretenberg/stdlib/hash/blake2s/blake2s.cpp```
20+
9. ```barretenberg/cpp/src/barretenberg/stdlib/hash/blake3s/blake3s.hpp```
21+
10. ```barretenberg/cpp/src/barretenberg/stdlib/hash/blake3s/blake3s.cpp```
22+
11. ```barretenberg/cpp/src/barretenberg/stdlib/hash/blake2s/blake_util.hpp```
23+
24+
#### Lookup related
25+
12. ```barretenberg/cpp/src/barretenberg/stdlib/primitives/plookup/plookup.cpp```
26+
- for `lookup_read<Builder>::get_lookup_accumulators` and its path from thereon
27+
13. ```barretenberg/cpp/src/barretenberg/stdlib_circuit_builders/plookup_tables/plookup_tables.hpp```
28+
```barretenberg/cpp/src/barretenberg/stdlib_circuit_builders/plookup_tables/plookup_tables.cpp```
29+
- for `ReadData<bb::fr> get_lookup_accumulators`
30+
14. ```barretenberg/cpp/src/barretenberg/stdlib_circuit_builders/plookup_tables/blake2s.hpp```
31+
- for BLAKE tables such as `BLAKE_XOR`, `BLAKE_XOR_ROTATE_16`, `BLAKE_XOR_ROTATE_8`, etc.
32+
33+
#### DSL/ACIR format
34+
15. ```barretenberg/cpp/src/barretenberg/dsl/acir_format/blake2s_constraint.hpp```
35+
16. ```barretenberg/cpp/src/barretenberg/dsl/acir_format/blake2s_constraint.cpp```
36+
17. ```barretenberg/cpp/src/barretenberg/dsl/acir_format/blake3_constraint.hpp```
37+
18. ```barretenberg/cpp/src/barretenberg/dsl/acir_format/blake3_constraint.cpp```
38+
39+
#### Tests
40+
19. ```barretenberg/cpp/src/barretenberg/crypto/blake2s/blake2s.test.cpp```
41+
- a set of test vectors that cover all message lengths from 0 to 72 bytes
42+
20. ```barretenberg/cpp/src/barretenberg/stdlib/hash/blake2s/blake2s.test.cpp```
43+
- a set of test vectors that cover varying message lengths up to 72 bytes including (powers of 2) boundaries, tested against the native implementation hash
44+
- single and double block tests
45+
- all witness, all constant and witness+constant message as input
46+
21. ```barretenberg/cpp/src/barretenberg/dsl/acir_format/blake2s_constraint.test.cpp```
47+
- ACIR integration test
48+
22. ```barretenberg/cpp/src/barretenberg/crypto/blake3s/blake3s.test.cpp```
49+
- a set of test vectors that cover all message lengths from 0 to 72 bytes
50+
- subset (unkeyed hash mode, with varying message length $\leq$ 1024 bytes) of official BLAKE3 test vectors
51+
- a test to check that inputs greater than 1024 bytes trigger the intended assertion
52+
23. ```barretenberg/cpp/src/barretenberg/stdlib/hash/blake3s/blake3s.test.cpp```
53+
- a set of test vectors that cover varying message lengths up to 72 bytes including (powers of 2) boundaries.
54+
- single and double block tests
55+
- all witness, all constant and witness+constant message as input
56+
24. ```barretenberg/cpp/src/barretenberg/dsl/acir_format/blake3_constraint.test.cpp```
57+
- ACIR integration test
58+
59+
60+
61+
### Summary of the module
62+
#### BLAKE2s
63+
Implements the unkeyed, sequential BLAKE2s and outputs a 32 byte hash. XOR+Rotate operations are implemented via lookups. The relevant files related to lookups used in BLAKE are mentioned above.
64+
65+
#### BLAKE3
66+
A restricted variant of BLAKE3 with inputs limited to $\leq$ 1024 bytes that generates a 32 byte hash. This kind of constraint on the input size simplifies the code and helps get rid of the recursive merkle-tree like operations on chunks (data of size 1024 bytes). This is because in Barretenberg, BLAKE3 is only used to hash inputs of size 32 bytes (or lesser).
67+
68+
### Documentation
69+
70+
BLAKE2s: https://www.blake2.net/blake2.pdf
71+
72+
BLAKE3: https://github.com/BLAKE3-team/BLAKE3-specs/blob/master/blake3.pdf
73+
74+
Lookup tables: https://github.com/AztecProtocol/aztec-packages/blob/next/barretenberg/cpp/src/barretenberg/stdlib_circuit_builders/plookup_tables/README.md
75+
76+
### Note
77+
Previously, certain inputs were pushing the addition overflows in `g` to beyond 3 bits (where `add_normalize` can tolerate up to 3 bits of overflow), causing failures. This has been addressed by calling `add_normalize` in the second half of every call to `g` to ensure that the overflow doesn't go beyond 3 bits. The input that was causing failures earlier has been added as a test case now. A detailed description of the issue can be found here: https://hackmd.io/@aztec-network/SyTHLkAWZx.

0 commit comments

Comments
 (0)