DEVOP-572: add CONTRIBUTING.md with dev-workstation security guidance by srt0422 · Pull Request #4 · allora-network/.github

srt0422 · May 13, 2026

Summary

Org-wide CONTRIBUTING.md covering the dev-workstation security baseline every contributor should adopt on day 1. Lives in the .github repo so it surfaces on every active repo via GitHub's CONTRIBUTING.md auto-surfacing.

Sections (one per acceptance criterion)

npm/pnpm/Corepack — ~/.npmrc template with ignore-scripts=true, fund=false, save-exact=true; Corepack pinning; audited per-package script re-enablement procedure.
Socket CLI — install + shell alias for socket npm install.
uv pip — drop-in replacement for raw pip with --require-hashes --only-binary=:all: as the default alias.
Publishing credentials — NPM_TOKEN / PYPI_API_TOKEN never local; publishing happens from CI; emergency-publish procedure cross-links to SECURITY-RUNBOOK Scenario C.
GitHub tokens — fine-grained only, classic PATs rejected, 90-day expiration cap, quarterly rotation cross-linked to runbook §7.
Lockfiles — commit, never hand-edit, never delete to fix errors.
Infection-suspected escalation — short, explicit STOP-and-go-here pointer to the runbook's Scenario A.
Code review expectations — second-engineer review for any new dep; suspicious-by-default lockfile-only diffs.
Links to runbook + IOC lists.

Style: TL;DR checklist up top for new joiners; rationale below for folks who want to understand before adopting. Each shell snippet is copy-paste-runnable with no manual filling-in-of-values.

Coordination with DEVOP-571

This PR cross-links to SECURITY-RUNBOOK.md (the runbook PR is #3). The runbook is the source of truth for incident response; this file is the source of truth for "what you do every day to avoid the incident." There's intentionally no behavioral overlap.

Per-repo README link

The last AC item ("Linked from each active repo's README") is not satisfied by this PR alone — it requires PRs in every active repo. That work is tracked separately under DEVOP-562 (the umbrella adoption ticket); when DEVOP-553's .npmrc rollout PRs land in each repo, the README link can ride alongside.

Linear

https://linear.app/alloralabs/issue/DEVOP-572

Test plan

Walk a new-joiner through the TL;DR checklist; time it (target: <15 minutes).
Verify each shell snippet runs as-is on macOS arm64.
Confirm GitHub auto-surfaces CONTRIBUTING.md as a contribution prompt in PR templates after merge.

🤖 Generated with Claude Code

Summary by cubic

Adds an org-wide CONTRIBUTING.md with a dev-workstation security baseline to reduce supply-chain risk. Lives in .github so GitHub auto-surfaces it across all repos.

New Features
- TL;DR checklist; cross-links to SECURITY-RUNBOOK.md; adds a cross-doc link status callout noting temporary 404s until sibling PRs land (DEVOP-571, DEVOP-561). Meets DEVOP-572 requirements.
- Node hardening: user ~/.npmrc with ignore-scripts=true, save-exact=true; Corepack pinning; audited one-off script re-enable guidance.
- Supply-chain guards: socket CLI aliases wrapping npm/pnpm installs; Python via uv pip with --require-hashes --only-binary=:all:.
- Credentials & process: publish from CI only (NPM_TOKEN/PYPI_API_TOKEN never local); fine‑grained GitHub tokens (90‑day max); commit lockfiles; second review required for new dependencies.
Migration
- Linking this doc from each repo’s README is tracked separately under DEVOP-562; this PR only adds the org-wide doc.

^{Written for commit 93f1460. Summary will update on new commits.}

Org-wide CONTRIBUTING.md covering the dev-workstation security baseline every contributor should adopt on day 1. Lives in the .github repo so it shows up on every active repo via GitHub's CONTRIBUTING.md auto-surfacing. Sections (one per acceptance criterion): 1. npm/pnpm/Corepack — user-level ~/.npmrc template with ignore-scripts=true, fund=false, save-exact=true; Corepack pinning; audited per-package script re-enablement procedure. 2. Socket CLI — install + shell alias for `socket npm install` wrapping. 3. uv pip — drop-in replacement for raw pip with --require-hashes + --only-binary=:all: as the default alias. 4. Publishing credentials — NPM_TOKEN / PYPI_API_TOKEN never local; publishing happens from CI; emergency-publish procedure cross-links to SECURITY-RUNBOOK Scenario C. 5. GitHub tokens — fine-grained only, classic PATs rejected, 90-day expiration cap, quarterly rotation cadence cross-linked to runbook §7. 6. Lockfiles — commit, never hand-edit, never delete to fix errors; frozen-lockfile in CI prevents mid-PR substitutions. 7. Infection-suspected escalation — short, explicit STOP-and-go-here pointer to the runbook's Scenario A. 8. Code review expectations — second-engineer review for any new dep; suspicious-by-default lockfile-only diffs. 9. Links to runbook + IOC lists. Style: TL;DR checklist up top for new joiners; rationale below for the folks who like to understand before adopting. Each shell snippet is copy-paste-runnable with no manual filling-in-of-values. Refs: https://linear.app/alloralabs/issue/DEVOP-572 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

cubic-dev-ai

cubic analysis

1 issue found across 1 file

Prompt for AI agents (unresolved issues)


Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="CONTRIBUTING.md">

<violation number="1" location="CONTRIBUTING.md:11">
P2: Broken internal links point to non-existent runbook/IOC files, so the guidance cannot be followed from this document. According to linked Linear issue DEVOP-572, this doc should direct contributors to the runbook actions, which is not currently navigable via these paths.</violation>
</file>

Linked issue analysis

Linked issue: DEVOP-572: Write CONTRIBUTING.md dev-workstation security guidance in .github org repo

Status	Acceptance criteria	Notes
✅	User-level ~/.npmrc template (ignore-scripts=true, fund=false).	The PR adds a `~/.npmrc` template with ignore-scripts=true and fund=false plus related guidance and examples.
✅	Use Corepack to pin pnpm version per repo.	The PR documents enabling Corepack and explains pinning via package.json packageManager field.
✅	Use `socket npm install` (free CLI) wrapping any direct `npm install`.	The PR documents installing Socket and provides shell alias examples to wrap npm/pnpm installs.
✅	Pip: prefer `uv pip install --require-hashes` over raw pip.	The PR prescribes uv as the pip replacement and defines an alias that includes --require-hashes and --only-binary flags.
✅	Never set NPM_TOKEN / PyPI tokens in local shell env — use trusted publishers and let CI publish.	The PR explicitly forbids storing publish tokens locally and describes CI-first publishing and emergency publish procedure tied to the runbook.
✅	Fine-grained PATs only; quarterly rotation reminder.	The PR requires fine-grained tokens, 90-day expiration, scoped permissions, and documents quarterly rotation notification process.
✅	What to do if you suspect infection: STOP, run the `SECURITY-RUNBOOK.md` Section 'Dev machine suspected infected'.	The PR includes a STOP instruction and links to the runbook Scenario A with symptom list and guidance to follow the runbook.
✅	PR merged into `allora-network/.github/CONTRIBUTING.md`.	This PR adds the CONTRIBUTING.md file to the .github repo path referenced by the acceptance criterion.

Architecture diagram

sequenceDiagram
    participant Dev as Developer Workstation
    participant GH as GitHub (allora-network)
    participant CI as CI Pipeline
    participant PKG as Package Registries (npm/PyPI)
    participant SOCK as Socket Risk Feed
    participant RU as SECURITY-RUNBOOK.md

    Note over Dev,RU: Dev-Workstation Security Baseline (CONTRIBUTING.md)

    Dev->>Dev: Apply ~/.npmrc template
    Note over Dev: ignore-scripts=true, save-exact=true, audit-level=high

    Dev->>Dev: Enable Corepack (corepack enable)
    Dev->>GH: Clone repo with "packageManager" field
    GH-->>Dev: Fetch exact pnpm/yarn version
    Dev->>PKG: npm install --ignore-scripts=false (audited case)

    Dev->>Dev: Install Socket CLI (npm install -g socket)
    Dev->>Dev: Configure shell aliases (npm-i, pnpm-i)
    Dev->>SOCK: socket npm install <package>
    alt Package flagged by Socket
        SOCK-->>Dev: Exit non-zero + alert
        Dev->>Dev: Bring alert to #security-alerts, do not override
    else Package clean
        SOCK-->>Dev: Allow install
    end

    Dev->>Dev: Install uv (curl -LsSf https://astral.sh/uv/install.sh)
    Dev->>Dev: Configure shell aliases (pip-i, pip-i-binary)
    Dev->>PKG: uv pip install --require-hashes --only-binary=:all:
    alt sdist-only package needed
        Dev->>PKG: uv pip install --no-binary=<pkg> (document exception)
    end

    Note over Dev,CI: Publishing Credentials (never local)

    Dev->>Dev: Remove NPM_TOKEN / PYPI_API_TOKEN from shell rc, .npmrc, .env
    CI->>PKG: Publish from CI (token written after install, deleted same step)
    alt Emergency local publish needed
        Dev->>RU: Follow Scenario C procedure
        RU-->>Dev: Clean environment + rotate token after publish
    end

    Note over Dev,GH: GitHub Token Hygiene

    Dev->>GH: Create fine-grained PAT (never classic)
    GH-->>Dev: Enforce 90-day max expiration
    Dev->>Dev: Quarterly rotation (respond to Slack DM)
    Dev->>Dev: Generate SSH key (ed25519 only, hardware-backed preferred)

    Note over Dev,GH: Incident Escalation

    alt Infection suspected
        Dev->>RU: Stop and follow Scenario A
        RU-->>Dev: Incident response instructions
    end

    Note over Dev,GH: Code Review

    Dev->>GH: Submit PR with new dependency
    GH->>GH: Require second-engineer review for new dep
    alt Lockfile-only diff (no package.json changes)
        GH->>Dev: Treat as suspicious by default
    end

    Note over Dev: Lockfiles committed, never hand-edited or deleted

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review, or fix all with cubic.}

The cubic review flagged broken internal links to SECURITY-RUNBOOK.md and the .github/security/ IOC files. Those paths are intentional — they target the canonical org-repo locations — but the documents themselves land in sibling PRs (DEVOP-571, DEVOP-561) that may not have merged yet when this PR lands. Rather than rewriting the links to point to inline fragments, add an explicit cross-doc-link-status callout near the top so readers know where the targets live and how to find them while sibling PRs are in flight. The links will resolve once all three PRs merge. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

srt0422 · May 13, 2026

Addressed in 93f1460. The links cubic flagged target the canonical paths the runbook (DEVOP-571) and IOC files (DEVOP-561) will live at; they 404 today only because those sibling PRs haven't merged yet. Rather than rewrite the links, added a cross-doc-link-status callout near the top of CONTRIBUTING.md so readers know where the targets live while the sibling PRs are in flight. Links will resolve once #2 and #3 merge.

cubic-dev-ai Bot reviewed May 13, 2026

View reviewed changes

Comment thread CONTRIBUTING.md

srt0422 added the shai-hulud Shai-Hulud supply-chain defense work label May 13, 2026

srt0422 requested a review from spooktheducks May 14, 2026 06:12

srt0422 added the needs-human-review label May 14, 2026

srt0422 assigned spooktheducks May 14, 2026

srt0422 requested a review from gh-allora May 14, 2026 20:05

spooktheducks merged commit 2c06f11 into allora-network:main May 14, 2026
1 check passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

DEVOP-572: add CONTRIBUTING.md with dev-workstation security guidance#4

DEVOP-572: add CONTRIBUTING.md with dev-workstation security guidance#4
spooktheducks merged 2 commits into
allora-network:mainallora-network/.github:mainfrom
srt0422:devop-572-contributingsrt0422/.github:devop-572-contributingCopy head branch name to clipboard

srt0422 commented May 13, 2026 •

edited by cubic-dev-ai Bot

Loading

Uh oh!

cubic-dev-ai Bot left a comment

Uh oh!

Uh oh!

srt0422 commented May 13, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Search code, repositories, users, issues, pull requests...

Conversation

srt0422 commented May 13, 2026 • edited by cubic-dev-ai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Sections (one per acceptance criterion)

Coordination with DEVOP-571

Per-repo README link

Linear

Test plan

Summary by cubic

Uh oh!

cubic-dev-ai Bot left a comment

Choose a reason for hiding this comment

cubic analysis

Linked issue analysis

Uh oh!

Uh oh!

srt0422 commented May 13, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

srt0422 commented May 13, 2026 •

edited by cubic-dev-ai Bot

Loading