Merge pull request #1290 from Queenode/fix-issues-1192-1191-1188-1189

Fix issues #1192, #1191, #1188, #1189

Author: Gbangbolaoluwagbemiga

.github/workflows/release.yml

@@ -3,15 +3,41 @@ on:
   push:
     tags:
       - "v*"
+  workflow_dispatch:
+    inputs:
+      override_mainnet_gate:
+        description: "Justification to override mainnet readiness gate"
+        required: false
+        type: string
 
-permissions: {}
+permissions:
+  contents: write
+  issues: read
 
 env:
   FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
 
 jobs:
+  mainnet-readiness-gate:
+    name: Check Mainnet Readiness
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/v') && contains(github.ref, '-mainnet') && github.event.inputs.override_mainnet_gate == ''
+    steps:
+      - name: Check open milestone issues
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          OPEN_ISSUES=$(gh issue list --repo ${{ github.repository }} --milestone "Mainnet Launch Readiness" --state open --json number,title --jq length)
+          if [ "$OPEN_ISSUES" -gt 0 ]; then
+            echo "::error::There are $OPEN_ISSUES open issues in the 'Mainnet Launch Readiness' milestone."
+            gh issue list --repo ${{ github.repository }} --milestone "Mainnet Launch Readiness" --state open
+            exit 1
+          fi
+
   build-and-release:
     name: Build (${{ matrix.target }})
+    needs: mainnet-readiness-gate
+    if: always() && needs.mainnet-readiness-gate.result != 'failure'
     runs-on: ${{ matrix.os }}
     permissions:
       contents: write

data/sarif/severity-map.yaml

@@ -1,5 +1,13 @@
+# Severity mapping for standard S-rules
 severity_mapping:
   info: low
   warning: medium
   error: high
   blocker: critical
+
+# ZK specific mapping guidelines (Z0xx namespace):
+# ZK rules follow the same severity levels as S-rules but have distinct vulnerability classes:
+# - missing-nullifier: blocker (critical)
+# - weak-fiat-shamir: error (high)
+# - constraint-under-specification: warning (medium)
+# - unused-public-input: info (low)

docs/adr/012-zk-toolchain-selection.md

@@ -0,0 +1,24 @@
+# ADR 012: ZK Toolchain Integration Path
+
+## Status
+
+Accepted
+
+## Context
+
+Zero-Knowledge (ZK) vulnerabilities require parsers and a static analysis model to detect issues like missing nullifier checks and weak Fiat-Shamir implementations. There are several ZK toolchains in the ecosystem (e.g., circom, arkworks, halo2, Noir). We need to decide which toolchains Sanctifier will support as a first-class citizen in v1, and which will be deferred to the future roadmap. This choice directly impacts the source languages our parsers need to support and the verifier contract patterns we prioritize. (See spike #1190 for research details).
+
+## Decision
+
+We will prioritize **circom + snarkjs** and **arkworks (Rust)** for v1 support.
+
+- **circom + snarkjs:** Has mature ecosystem tooling and is widely used across the industry for ZK rollups and application circuits.
+- **arkworks:** Given our existing Rust infrastructure and Soroban's native Rust environment, supporting arkworks aligns well with our current tech stack and ecosystem.
+
+Other toolchains, such as **Noir** and **halo2**, will be deferred to the future roadmap.
+
+## Consequences
+
+1. **Parser Scope (#1227, #1228, #1229):** The parsers must be designed to parse Circom source files and Rust (for arkworks). We will not build parser support for Noir at this time.
+2. **Example Contracts (#1216):** The first verifier contract patterns and test suites built will target Circom/snarkjs Groth16/Plonk verifiers and arkworks-based verifiers.
+3. **Roadmap:** We must explicitly communicate to users that Noir and halo2 are not supported in the initial ZK ruleset release, managing expectations.

docs/error-codes.md

@@ -1,5 +1,13 @@
 # Sanctifier Error Code Mapping
 
+## CLI Exit Codes
+
+When running `sanctifier-cli`, the process will exit with one of the following codes:
+- **`0` (SUCCESS)**: Analysis succeeded with no triggered findings.
+- **`1` (FINDINGS_FOUND)**: Findings were detected and the active profile triggered on them.
+- **`2` (ERROR)**: Unrecoverable error (e.g., invalid path, config parse failure, I/O error).
+
+---
 Sanctifier uses a unified finding code system across `sanctifier-core` and `sanctifier-cli` outputs.
 
 | Code | Category | Meaning |

docs/rule-authoring-guide.md

@@ -212,6 +212,14 @@ fn collect_pat_idents(pat: &Pat, out: &mut HashSet<String>) {
 Not handling `Pat::Tuple` / `Pat::Struct` is the most common source of false negatives
 in taint passes — taint silently disappears at the destructure boundary.
 
+## 8. ZK Rules (Z-series) Namespace
+
+Sanctifier introduces a dedicated `Z001-Z0NN` numbering convention for Zero-Knowledge (ZK) specific vulnerability rules, functioning alongside the existing `S0xx` static-rule namespace.
+
+When authoring ZK rules:
+- **Namespace:** All ZK rules MUST use the `Z` prefix (e.g., `Z001`, `Z002`).
+- **Severity Mapping:** ZK vulnerabilities often have different blast-radius characteristics than typical Soroban bugs. Explicit severity mapping guidance is required to ensure consistent rating by reviewers. Refer to `schemas/severity-taxonomy.schema.json` and `data/sarif/severity-map.yaml` for specific vulnerability classes (e.g., missing nullifier checks, weak fiat-shamir).
+
 ---
 
 ## Further Reading

schemas/severity-taxonomy.schema.json

@@ -8,7 +8,8 @@
       "additionalProperties": {
         "type": "string",
         "enum": ["low", "medium", "high", "critical"]
-      }
+      },
+      "description": "Maps generic severities (info, warning, error, blocker) to standard SARIF severity levels. For ZK vulnerabilities (Z-series), map severity explicitly based on blast-radius (e.g. missing nullifier checks -> critical, weak fiat-shamir -> high, constraint under-specification -> medium, unused public input -> low)."
     }
   }
 }

tooling/sanctifier-cli/tests/cli_tests.rs

@@ -1434,3 +1434,42 @@ fn test_no_profile_no_exit_code_exits_zero_with_findings() {
         .assert()
         .success();
 }
+
+/// Verify documented CLI exit codes (0 = SUCCESS, 1 = FINDINGS_FOUND, 2 = ERROR).
+#[test]
+fn test_documented_exit_codes() {
+    let valid_fixture = env::current_dir()
+        .unwrap()
+        .join("tests/fixtures/valid_contract.rs");
+    let vulnerable_fixture = env::current_dir()
+        .unwrap()
+        .join("tests/fixtures/vulnerable_contract.rs");
+    
+    // Code 0: SUCCESS (no findings)
+    Command::cargo_bin("sanctifier")
+        .unwrap()
+        .arg("analyze")
+        .arg(&valid_fixture)
+        .arg("--profile")
+        .arg("ci")
+        .assert()
+        .code(0);
+
+    // Code 1: FINDINGS_FOUND (has findings with strict profile)
+    Command::cargo_bin("sanctifier")
+        .unwrap()
+        .arg("analyze")
+        .arg(&vulnerable_fixture)
+        .arg("--profile")
+        .arg("ci")
+        .assert()
+        .code(1);
+
+    // Code 2: ERROR (e.g., invalid path)
+    Command::cargo_bin("sanctifier")
+        .unwrap()
+        .arg("analyze")
+        .arg("path/that/does/not/exist.rs")
+        .assert()
+        .code(2);
+}