Skip to content
vana-comPublic

About

Shared GitHub Actions security policy for Vana repositories

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

59 Commits

Folders and files

Repository files navigation

vana-com shared GitHub configuration

This repository contains Vana's trusted EVM private-key policy. Gitleaks is the authoritative primary scanner. A separate advisory job enriches only Gitleaks findings with EVM address derivation and public-chain liveness checks.

What the CI check does

The reusable workflow scans every commit introduced by a pull request. For each commit it scans complete snapshots of only that commit's changed files. This matters for two cases that an endpoint diff misses:

  • a key added in one commit and removed in a later commit; and
  • a value added below an unchanged privateKey declaration.

The rule finds 64-hex-character EVM private-key candidates when they are within two lines of a secret-shaped declaration or stored in a secret-named file such as private-key. It intentionally does not scan arbitrary 32-byte hashes. Findings are redacted; the workflow prints a commit ID, never the candidate value. The advisory job deduplicates the primary candidates across the whole range before it queries RPC endpoints. It reports active-address findings and incomplete endpoint checks as warnings; an internal scanner or inventory error still fails that job.

The advisory scanner runs only code from the immutable policy checkout. It materializes caller Git objects as data and does not run caller scripts, install caller dependencies, or use a caller package lifecycle. Its implementation is Apache-2.0 because it adapts Vana smart-contracts PR 69 by Maciej; see scripts/evm-key-liveness/NOTICE.

This release does not detect BIP-39 mnemonics. A reliable mnemonic rule must validate the BIP-39 checksum against its word list to avoid flagging normal prose. Gitleaks alone cannot do that deterministically, so this project makes no mnemonic-detection claim.

Use from a protected pull-request workflow

Create this small caller workflow in each participating repository:

name: secret scan
on:
  pull_request:

permissions:
  contents: read

jobs:
  evm-key-scan:
    uses: vana-com/.github/.github/workflows/evm-key-scan.yml@<released-commit-sha>

Replace <released-commit-sha> with the 40-character commit ID of a reviewed release. This pin is immutable, so all repositories run the reviewed central implementation. Keep the small caller workflow code-owned, so a pull request cannot change the central pin without the security owner's review. The Gitleaks scan is the authoritative job; whether it is required for merge remains a separate, approved branch-protection decision in each caller repository.

The workflow pins Gitleaks v8.30.1 and verifies the downloaded archive's SHA-256 before executing it. Action references use immutable commit IDs. It checks out the pull request and the trusted policy as sibling directories, so untrusted pull-request content cannot shadow the policy checkout.

Optional local pre-push safeguard

Git hooks are not policy: they can be missing, stale, or bypassed with git push --no-verify. CI and branch protection are the enforcement layer. The hook is still useful because it stops an accidental public leak before it leaves the workstation.

Clone this repository at the same reviewed release commit somewhere durable. From that checkout, run:

scripts/install-pre-push.sh --repo /path/to/public-repo --ref <released-commit-sha>

The installer requires the selected checkout to come from vana-com/.github, match the exact release SHA, and have no local changes. It installs the pinned Gitleaks binary when the local copy is missing or fails checksum verification, then records the selected policy checkout in a managed launcher. No shell environment setup is required. Use status to inspect the launcher and uninstall to remove it. To move a repository to a newer reviewed release, uninstall with the old release SHA, then install with the new release SHA.

The installer refuses to overwrite or remove an unmanaged hook. Use a hook manager or merge the launcher deliberately when another pre-push hook already exists.

The hook verifies the policy checkout SHA, verifies that the checkout has no local changes, and verifies the Gitleaks binary checksum before each push. It does not download tools during git push; if the tool is missing or has the wrong checksum, it fails closed and asks the developer to re-run the installer. It sends no source or candidate values over the network. For a new remote branch, it scans only commits not reachable from locally fetched refs/remotes/<remote> tips; run git fetch <remote> first if those refs may be stale.

False positives and remediation

Inline gitleaks:allow comments are disabled. For published compatibility vectors, add a centrally reviewed exception that requires both the exact value and an anchored fixture or documentation path. Never allowlist a commit, a path alone, or a value alone.

Do not treat a value as harmless because it appears in a test or load-test file. A reviewed historical inventory found operational Moksha accounts in SDK load-test data; those values are intentionally not excepted. Exceptions in this policy are limited to independently verified inert compatibility or dummy constants, an invalid configuration sentinel, and a documentation mock.

One additional reviewed exception covers 86 published upstream wallet-library example values that Vana vendors under 14 exact stats-client/node_modules paths. It requires both a listed value and one of those anchored paths. It does not exempt node_modules generally, a path suffix or shadow path, or a value outside the reviewed set.

If the check finds a real key, remove it from all unpushed commits and rotate it. Deleting it in a later commit does not make it safe: the earlier commit can still be uploaded, cloned, cached, or indexed.

Verify a checkout

scripts/install-gitleaks.sh .tools/gitleaks
GITLEAKS_BIN=$PWD/.tools/gitleaks/gitleaks tests/run.sh
npm ci --ignore-scripts --prefix scripts/evm-key-liveness
GITLEAKS_BIN=$PWD/.tools/gitleaks/gitleaks node --test scripts/evm-key-liveness/scan.test.mjs

The test harness covers inline keys, clean hashes, add-then-remove history, split-line declarations, path-and-value exceptions, commit messages, merge resolutions, secret-named files, upstream-vendored-example exception bounds, and fail-closed argument and tool failures. It creates its own throwaway Git repository. The liveness tests use mocked RPC responses for scalar validation, address derivation, active and inactive accounts, incomplete checks, redaction, and range materialization.

Codex PR review

.github/workflows/codex-review-reusable.yml is a shared, workflow_call reusable workflow that runs an automated Codex review on every pull request and posts the result as a PR comment. Consuming repositories no longer maintain their own copy of this logic, so improvements (the fork-PR safety gate, prompt tuning, cost tracking) land once here instead of drifting across repos. Cost tracking and a couple of other proposed additions are being held for a follow-up PR pending review — see that PR's description for what's outstanding.

Adopt it in a repository

Add this thin caller workflow at .github/workflows/codex-review.yml in the consuming repository:

name: Codex review
on:
  pull_request:
    types: [opened, reopened, synchronize]

# Reusable-workflow permissions only flow downward: the caller must grant at
# least what the called workflow's jobs request, or GitHub rejects the call
# before anything runs (startup_failure). The review job needs contents:read;
# the comment job needs issues:write/pull-requests:write to post the review.
permissions:
  contents: read
  issues: write
  pull-requests: write

jobs:
  review:
    uses: vana-com/.github/.github/workflows/codex-review-reusable.yml@<commit-sha>
    secrets: inherit

secrets: inherit forwards the calling repository's OPENAI_API_KEY (an organization or repository secret) to the reusable workflow. This is the standard pattern for an org-wide reusable workflow consumed by many repositories: it avoids naming every secret at every call site, and this workflow only reads a single well-known secret name (OPENAI_API_KEY), so there is no risk of over-sharing unrelated secrets into it. Repositories that prefer to be explicit can instead pass secrets: { OPENAI_API_KEY: ...}.

This workflow is pinned to an immutable commit SHA, matching the EVM key-scan workflow above -- both are security-adjacent: secrets: inherit means an unreviewed push to this repo's main would otherwise reach every consuming repository's OPENAI_API_KEY with no gate in between. An earlier version of this doc argued @main was fine here because a bad prompt is "annoying, not dangerous" -- that reasoning missed that the actual risk isn't prompt quality, it's secret exposure, and two independent automated reviews flagged it before a human did. Bump the pin deliberately (a one-line change per consuming repo) when adopting a new commit here, the same as the key-scan workflow.

Inputs

Input Default Purpose
model gpt-5.6-sol Codex model used for the review.
effort high Reasoning effort passed to the model.

Override either from the caller when needed:

jobs:
  review:
    uses: vana-com/.github/.github/workflows/codex-review-reusable.yml@<commit-sha>
    with:
      model: gpt-5.6-terra
      effort: medium
    secrets: inherit

These were previously read from vars.CODEX_REVIEW_MODEL / vars.CODEX_REVIEW_EFFORT org variables in each repo's own copy of this workflow. A workflow_call reusable workflow's own vars.* references do resolve against the calling repository's configuration variables, but relying on that implicitly is a poor fit for a workflow meant to be called from many repositories: the effective model/effort for a given caller would depend on org- or repo-level variables that are invisible at the call site itself. Explicit inputs make the override visible in the caller's own workflow file and keep the contract self-documenting; repos that already set CODEX_REVIEW_MODEL/CODEX_REVIEW_EFFORT variables can pass them through explicitly with with: { model: ${{ vars.CODEX_REVIEW_MODEL }}, ... }.

The reviewer never runs on pull requests from forks, because fork PRs do not receive repository secrets — this is enforced inside the reusable workflow itself (if: github.event.pull_request.head.repo.full_name == github.repository on the review job), not something each caller needs to re-implement.

License

The repository root is MIT licensed. The isolated scripts/evm-key-liveness adaptation is Apache-2.0 licensed; its NOTICE preserves the source attribution.

Preview authentication control plane

Step 0 uses existing dev databases and https://account-dev.vana.org for every app. Configure the Vercel Preview builds with those peer settings before enabling the workflow. The workflow assigns an exact alias and enrolls exact OAuth callback URLs for each eligible deployment. Mobile previews run in the browser.

The reusable workflow checks out its own automation at an immutable commit. The credentialed caller and app matrix run from the repository's default branch (main). Pull request and deployment events start a separate signal workflow with no secrets, repository checkout or artifacts. A read-only admission job uses GitHub to confirm that the signal identifies a same-repository PR before the credentialed job can start. Each repository has one queue with up to 100 waiting jobs, so callback writes from different apps in that repository are serialized. Use distinct Account clients for each repository. GitHub Actions concurrency

Enable previews

  1. Deploy the Account narrow callback API to account-dev. Verify the dev database, peer app URLs, and Vercel DNS for the preview domain.
  2. Create the preview-auth GitHub environment and allow deployments from main only. Add the repository's read-only Doppler service token to that environment as DOPPLER_PREVIEW_TOKEN.
  3. Merge the signal and credentialed caller to main. Pin the caller to a reviewed organization workflow commit. Set the repository variable PREVIEW_AUTH_ENABLED to true when configuration is ready.

Save the signal as .github/workflows/preview-deployment-signal.yml.

name: Preview deployment signal
on:
  deployment_status:
  pull_request:
    types: [opened, reopened, synchronize, edited, closed]
permissions: {}
jobs:
  signal:
    runs-on: ubuntu-24.04
    steps:
      - run: echo "Signal only. Fork PRs are ineligible for authenticated previews."

The credentialed caller responds to completed signals, or runs from main on the daily schedule or manual dispatch.

name: Preview auth
on:
  workflow_run:
    workflows: ['Preview deployment signal']
    types: [completed]
  schedule:
    - cron: '23 5 * * *'
  workflow_dispatch:
    inputs:
      decommission:
        description: Drain this repository's preview aliases and callbacks
        type: boolean
        default: false
permissions:
  contents: read
  pull-requests: write
  deployments: read
jobs:
  preview:
    if: github.ref == 'refs/heads/main'
    uses: vana-com/.github/.github/workflows/preview-auth-reusable.yml@<reviewed-40-character-sha>
    with:
      target_branch: dev
      doppler_project: preview-automation
      doppler_config: dev
      decommission: ${{ inputs.decommission == true }}
      app_matrix: >-
        [{"app":"web","project_id":"prj_9MpHdKQiODnS6V9m4MOtwAIKaabV","client_id_key":"WEB_CLIENT_ID","callback_paths":["/oauth/callback"]}]
    secrets: inherit

The caller trusts the workflow-run metadata GitHub sends. It looks up the PR and its current head through the GitHub API before reading Vercel deployments or changing preview state. GitHub workflow run events

Each matrix entry names an app, its Vercel project and its exact callback paths. The org-owned manifest binds app names to repository and project IDs. Set callback_paths: [] for apps without callbacks. The optional needs_neon field defaults to false. If it is true and a migrations_path is present, the app reports required-unavailable before publishing. Per-PR Neon provisioning is future work. domain defaults to vana.boo.

Account configuration

The caller's Doppler config supplies VERCEL_TOKEN and TEAM_ID. For Account, it also supplies ACCOUNT_ADMIN_TOKEN and PREVIEW_DEV_CLIENT_IDS. The token must have access to GET and POST on the narrow /redirect-uris endpoint. PREVIEW_DEV_CLIENT_IDS is a JSON array or comma-separated list of dev OAuth client IDs exclusive to the calling repository. Include retired clients until their callbacks are drained. Use [] for a repository with no Account clients. Each callback-enabled app's client_id_key points to one of those IDs and must match ^[A-Z0-9_]+_CLIENT_ID$. If the config defines ACCOUNT_ORIGIN, its value must be https://account-dev.vana.org. account_wiring_mode accepts existing-clients.

Every callback write reads the client's existing list and refuses a client with a known preview callback owned by another repository. Each write adds or removes one exact URI while preserving other entries.

Cleanup and retirement

A same-repository PR qualifies while it is open on the configured target branch and has an ordinary READY Preview deployment for its exact current head, repository and project. Opening or reopening a PR can reuse a matching existing deployment. A failed build leaves the last good alias intact.

Web, Community and My Two Cents need the Vercel PR ID at build or runtime. When the only verified native build predates the PR, the workflow asks Vercel to rebuild that deployment. The workflow waits if a matching post-PR build already exists. It enrolls callbacks and assigns an alias only after a READY deployment identifies the current PR and was created after it opened. Vercel system environment variables

Closing a PR or retargeting it away from the configured branch removes its owned aliases before trying Account callbacks. Closed PR callbacks are identified by the owned app/PR hostname, including historical paths removed from the matrix. The daily sweep also checks all repo-owned projects and dev clients, including apps removed from the current matrix. It also checks open PRs for a missed first publication. The sweep can publish a missing alias or repair an expired target when a READY deployment matches the open PR's current head, repository and app project. It reports expired aliases that need a new build. Newly opened PRs and unaffected apps without a matching build wait for the next deployment.

To retire a caller, set the repository variable PREVIEW_AUTH_DECOMMISSION to true and let existing preview jobs settle. Run the caller manually with decommission: true and keep the allowlist and ownership entries in place. The run drains owned aliases and exact callbacks even for open PRs. Disable PREVIEW_AUTH_ENABLED and remove the caller only after the run reports decommissioned.

Alias writes use the Vercel API. Cleanup checks the current target and only deletes a verified alias by its UID. It confirms deletion by reading the host again. A target whose ownership cannot be verified needs operator review. Vercel does not document a conditional alias delete, so avoid manual writes to these hostnames during reconciliation. Vercel Alias API

Run node --test scripts/preview-auth.test.mjs for the local lifecycle tests. The tests exercise the production HTTP adapter through fake GitHub, Account and Vercel responses.

About

Shared GitHub Actions security policy for Vana repositories

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages