Skip to content

Commit 638fda7

Browse files
aksOpsPaperclip-Paperclipclaude
committed
chore(bootstrap): RAN-46 engineering bootstrap (security, runbooks, OpenSSF wiring)
Lands the static side of the one-shot RAN-46 bootstrap. No code or build changes — only governance + supply-chain artifacts the rest of the AC list depends on. Adds: - shared/runbooks/{release,rollback,first-time-setup,engineering-standards}.md (release.md is the gate referenced by the CEO bootstrap precondition for every downstream RAN-* product issue) - SECURITY.md (private-disclosure contact, supported versions, scope) - AGENTS.md (repo-root entry point pointing at CLAUDE.md and runbooks) - .bestpractices.json (OpenSSF Best Practices self-assessment skeleton — project_id pending board registration per AC #8) - .github/dependabot.yml (Maven + GHA + npm, weekly grouped) - .github/workflows/codeql.yml + scorecard.yml (every action pinned by commit SHA per Scorecard Pinned-Dependencies) - scripts/setup-git-signed.sh (idempotent repo-local ssh-signing config) - README.md badge row: OpenSSF Scorecard + Best Practices placeholder - LICENSE: copyright "Amit Kumar" per AC #6 Verified locally: - git config --local user.signingkey resolves to ~/.ssh/id_ed25519.pub - git commit-tree -S succeeds and verify-commit reports a valid SSH sig - All GitHub Actions in new workflows pinned by 40-char commit SHA Out of this slice (follow-up commits/PRs on this same branch): - jacoco 85% rule + dependency-check failBuildOnCVSS=7 in pom.xml - SHA-pinning of existing ci-java.yml / beta-java.yml / release-java.yml - Branch protection + Dependabot security-updates + private vuln reporting (driven post-merge via gh api — recorded as RAN-46 comments) - Hello-world deploy proof (blocked on AC #10 scope decision from @coo) - paperclip Project codebase.repoUrl PATCH (final step after this PR merges) Refs RAN-46. Co-Authored-By: Paperclip <noreply@paperclip.ing> Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1 parent 8f1ce18 commit 638fda7

13 files changed

Lines changed: 999 additions & 1 deletion

File tree

‎.bestpractices.json‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
{
2+
"$schema": "https://bestpractices.coreinfrastructure.org/projects.schema.json",
3+
"_comment": "OpenSSF Best Practices self-assessment skeleton for RandomCodeSpace/codeiq. The numeric project_id and badge URL are populated by a board admin after registering the project at https://www.bestpractices.dev/ — RAN-46 AC #8 calls this out as auth-blocked. Once the registration is complete, fill `project_id` and re-render the README badge with the resolved URL.",
4+
"project_id": null,
5+
"name": "codeiq",
6+
"description": "Deterministic code knowledge graph — scans codebases to map services, endpoints, entities, infrastructure, auth patterns, and framework usage. No AI, pure static analysis.",
7+
"homepage_url": "https://github.com/RandomCodeSpace/codeiq",
8+
"repo_url": "https://github.com/RandomCodeSpace/codeiq",
9+
"license": "MIT",
10+
"level": "passing",
11+
"status": {
12+
"basics": "self-assessed-passing",
13+
"change_control": "self-assessed-passing",
14+
"reporting": "self-assessed-passing",
15+
"quality": "self-assessed-passing",
16+
"security": "self-assessed-passing",
17+
"analysis": "self-assessed-passing"
18+
},
19+
"evidence": {
20+
"vulnerability_report_process": "SECURITY.md",
21+
"release_process": "shared/runbooks/release.md",
22+
"rollback_process": "shared/runbooks/rollback.md",
23+
"first_time_setup": "shared/runbooks/first-time-setup.md",
24+
"engineering_standards": "shared/runbooks/engineering-standards.md",
25+
"license_file": "LICENSE",
26+
"build_reproducible": "mvn -B -ntp clean verify",
27+
"ci_workflow": ".github/workflows/ci-java.yml",
28+
"code_scanning": ".github/workflows/codeql.yml",
29+
"supply_chain_scorecard": ".github/workflows/scorecard.yml",
30+
"dependency_updates": ".github/dependabot.yml",
31+
"signed_commits": "scripts/setup-git-signed.sh",
32+
"secret_scanning": "GitHub repo setting (secret_scanning + push_protection enabled)",
33+
"static_analysis": "SpotBugs (mvn spotbugs:check) + SonarCloud Quality Gate",
34+
"vulnerability_scanning": "OWASP Dependency-Check (mvn dependency-check:check) + Dependabot security updates"
35+
},
36+
"audit": {
37+
"self_assessment_date": "2026-04-25",
38+
"self_assessment_author": "TechLead (RAN-46)",
39+
"registration_blocker": "https://www.bestpractices.dev/ requires human OAuth/form. Tracked under RAN-46 AC #8."
40+
}
41+
}

‎.github/dependabot.yml‎

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
# Dependabot configuration for codeiq.
2+
# Docs: https://docs.github.com/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
3+
#
4+
# Strategy:
5+
# * weekly cadence — keeps the noise floor low while still catching CVEs early
6+
# * grouped updates per ecosystem so PR fan-out stays manageable
7+
# * security updates fire whenever needed regardless of the weekly slot
8+
#
9+
# RAN-46 AC #4: Dependabot (security + version updates, weekly, grouped). Also
10+
# enable repo-level "Dependabot security updates" via gh api (the version-updates
11+
# below cover routine bumps; security updates are the reactive channel).
12+
13+
version: 2
14+
updates:
15+
# ----- Maven (the codeiq application) -----
16+
- package-ecosystem: "maven"
17+
directory: "/"
18+
schedule:
19+
interval: "weekly"
20+
day: "monday"
21+
time: "08:00"
22+
timezone: "Etc/UTC"
23+
open-pull-requests-limit: 10
24+
labels:
25+
- "type:dependencies"
26+
- "area:backend"
27+
commit-message:
28+
prefix: "chore(deps)"
29+
include: "scope"
30+
groups:
31+
spring:
32+
patterns:
33+
- "org.springframework*"
34+
- "org.springframework.boot:*"
35+
- "org.springframework.security:*"
36+
- "org.springframework.ai:*"
37+
jackson:
38+
patterns:
39+
- "com.fasterxml.jackson*"
40+
neo4j:
41+
patterns:
42+
- "org.neo4j:*"
43+
- "org.neo4j.driver:*"
44+
antlr:
45+
patterns:
46+
- "org.antlr:*"
47+
maven-plugins:
48+
patterns:
49+
- "org.apache.maven.plugins:*"
50+
- "org.codehaus.*"
51+
- "org.jacoco:*"
52+
- "com.github.spotbugs:*"
53+
- "org.owasp:*"
54+
- "org.sonarsource.scanner.maven:*"
55+
- "org.sonatype.central:*"
56+
test-libs:
57+
patterns:
58+
- "org.junit.jupiter:*"
59+
- "org.mockito:*"
60+
- "org.assertj:*"
61+
- "org.hamcrest:*"
62+
- "com.h2database:*"
63+
64+
# ----- GitHub Actions (CI / release / security) -----
65+
- package-ecosystem: "github-actions"
66+
directory: "/"
67+
schedule:
68+
interval: "weekly"
69+
day: "monday"
70+
time: "08:00"
71+
timezone: "Etc/UTC"
72+
open-pull-requests-limit: 5
73+
labels:
74+
- "type:dependencies"
75+
- "area:ci"
76+
commit-message:
77+
prefix: "chore(actions)"
78+
include: "scope"
79+
groups:
80+
actions:
81+
patterns:
82+
- "*"
83+
84+
# ----- Frontend (npm under src/main/frontend) -----
85+
- package-ecosystem: "npm"
86+
directory: "/src/main/frontend"
87+
schedule:
88+
interval: "weekly"
89+
day: "monday"
90+
time: "08:00"
91+
timezone: "Etc/UTC"
92+
open-pull-requests-limit: 5
93+
labels:
94+
- "type:dependencies"
95+
- "area:frontend"
96+
commit-message:
97+
prefix: "chore(frontend)"
98+
include: "scope"
99+
groups:
100+
react:
101+
patterns:
102+
- "react"
103+
- "react-dom"
104+
- "@types/react*"
105+
ant-design:
106+
patterns:
107+
- "antd"
108+
- "@ant-design/*"
109+
vite:
110+
patterns:
111+
- "vite"
112+
- "@vitejs/*"
113+
echarts:
114+
patterns:
115+
- "echarts"
116+
- "echarts-for-react"
117+
eslint:
118+
patterns:
119+
- "eslint*"
120+
- "@eslint/*"
121+
- "@typescript-eslint/*"
122+
typescript:
123+
patterns:
124+
- "typescript"
125+
- "@types/*"

‎.github/workflows/codeql.yml‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
# CodeQL code-scanning analysis for codeiq.
2+
# RAN-46 AC #4 (code scanning enabled). Runs on push, on PR, and on a weekly cron
3+
# so we don't drift if someone forgets to push for a while.
4+
#
5+
# Java is the only first-class language at the moment. The bundled React UI under
6+
# src/main/frontend is JS/TS — added as a second matrix entry so frontend changes
7+
# also get scanned without slowing down Java analysis.
8+
9+
name: CodeQL
10+
11+
on:
12+
push:
13+
branches: [main]
14+
pull_request:
15+
branches: [main]
16+
schedule:
17+
# Mondays 07:00 UTC
18+
- cron: "0 7 * * 1"
19+
workflow_dispatch:
20+
21+
permissions: read-all
22+
23+
jobs:
24+
analyze:
25+
name: Analyze (${{ matrix.language }})
26+
runs-on: ubuntu-latest
27+
timeout-minutes: 60
28+
permissions:
29+
security-events: write
30+
packages: read
31+
contents: read
32+
actions: read
33+
34+
strategy:
35+
fail-fast: false
36+
matrix:
37+
include:
38+
- language: java-kotlin
39+
build-mode: manual
40+
- language: javascript-typescript
41+
build-mode: none
42+
43+
steps:
44+
- name: Harden runner egress
45+
# step-security/harden-runner v2.19.0
46+
uses: step-security/harden-runner@8d3c67de8e2fe68ef647c8db1e6a09f647780f40
47+
with:
48+
egress-policy: audit
49+
50+
- name: Checkout code
51+
# actions/checkout v6.0.2
52+
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
53+
with:
54+
persist-credentials: false
55+
56+
- name: Set up JDK 25
57+
if: matrix.language == 'java-kotlin'
58+
# actions/setup-java v5.2.0
59+
uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654
60+
with:
61+
distribution: temurin
62+
java-version: "25"
63+
cache: maven
64+
65+
- name: Initialize CodeQL
66+
# github/codeql-action/init v3.35.2
67+
uses: github/codeql-action/init@ce64ddcb0d8d890d2df4a9d1c04ff297367dea2a
68+
with:
69+
languages: ${{ matrix.language }}
70+
build-mode: ${{ matrix.build-mode }}
71+
queries: security-and-quality
72+
73+
- name: Build with Maven (Java only)
74+
if: matrix.language == 'java-kotlin'
75+
run: mvn -B -ntp -DskipTests -Dspotbugs.skip=true -Ddependency-check.skip=true clean package
76+
77+
- name: Perform CodeQL analysis
78+
# github/codeql-action/analyze v3.35.2
79+
uses: github/codeql-action/analyze@ce64ddcb0d8d890d2df4a9d1c04ff297367dea2a
80+
with:
81+
category: "/language:${{ matrix.language }}"

‎.github/workflows/scorecard.yml‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
# OpenSSF Scorecard supply-chain analysis.
2+
# RAN-46 AC #9. Best-effort target — no hard numeric floor; Scorecard does not gate merge.
3+
# Docs: https://github.com/ossf/scorecard-action
4+
5+
name: Scorecard supply-chain security
6+
7+
on:
8+
push:
9+
branches: [main]
10+
schedule:
11+
# Mondays 06:00 UTC
12+
- cron: "0 6 * * 1"
13+
workflow_dispatch:
14+
15+
# Restrict the default GITHUB_TOKEN to read-only; the steps below request the
16+
# narrow scopes they actually need.
17+
permissions: read-all
18+
19+
jobs:
20+
analysis:
21+
name: Scorecard analysis
22+
runs-on: ubuntu-latest
23+
permissions:
24+
# Required for upload to the code-scanning Security tab.
25+
security-events: write
26+
# Required to read OIDC token for publish_results.
27+
id-token: write
28+
# Default scopes for actions/checkout.
29+
contents: read
30+
actions: read
31+
32+
steps:
33+
- name: Harden runner egress
34+
# step-security/harden-runner v2.19.0
35+
uses: step-security/harden-runner@8d3c67de8e2fe68ef647c8db1e6a09f647780f40
36+
with:
37+
egress-policy: audit
38+
39+
- name: Checkout code
40+
# actions/checkout v6.0.2
41+
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
42+
with:
43+
persist-credentials: false
44+
45+
- name: Run Scorecard analysis
46+
# ossf/scorecard-action v2.4.3
47+
uses: ossf/scorecard-action@4eaacf0543bb3f2c246792bd56e8cdeffafb205a
48+
with:
49+
results_file: results.sarif
50+
results_format: sarif
51+
# Publish the results so they appear on the public Scorecard dashboard.
52+
publish_results: true
53+
54+
- name: Upload Scorecard SARIF (artifact)
55+
# actions/upload-artifact v7.0.1
56+
uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a
57+
with:
58+
name: scorecard-sarif
59+
path: results.sarif
60+
retention-days: 5
61+
62+
- name: Upload SARIF to GitHub code-scanning
63+
# github/codeql-action/upload-sarif v3.35.2
64+
uses: github/codeql-action/upload-sarif@ce64ddcb0d8d890d2df4a9d1c04ff297367dea2a
65+
with:
66+
sarif_file: results.sarif

‎AGENTS.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
# AGENTS.md — codeiq
2+
3+
> **Repo-root entry point for any agent collaborator.** This file is intentionally short and lists pointers; the canonical contents live elsewhere and are linked from here.
4+
5+
## What this repo is
6+
7+
codeiq is a CLI + read-only server that builds a deterministic code-knowledge graph over a codebase. No AI, no external APIs — pure static analysis. See [`/CLAUDE.md`](CLAUDE.md) for the architecture, package map, pipeline, conventions, and gotchas.
8+
9+
## Pointers, in priority order
10+
11+
1. **Read [`/CLAUDE.md`](CLAUDE.md) first.** It is the SSoT for architecture, build/test commands, package layout, and the long-tail of "things that bite you on this codebase."
12+
2. **Then [`/shared/runbooks/engineering-standards.md`](shared/runbooks/engineering-standards.md).** Coverage, CVE, signed-commits, and quality-gate policy.
13+
3. **Then the runbooks you'll actually need:**
14+
- [`shared/runbooks/first-time-setup.md`](shared/runbooks/first-time-setup.md) — get from clean clone to green local build.
15+
- [`shared/runbooks/release.md`](shared/runbooks/release.md) — how to ship; gates downstream RAN-* product work.
16+
- [`shared/runbooks/rollback.md`](shared/runbooks/rollback.md) — when a ship goes bad.
17+
4. **Security**: [`/SECURITY.md`](SECURITY.md) for disclosure; private reports only.
18+
19+
## Hard rules for any agent doing work in this repo
20+
21+
- **Branch off `main`.** Never commit to `main` directly.
22+
- **Sign every commit.** The repo-local config (`scripts/setup-git-signed.sh`) makes this automatic; do not rewrite it.
23+
- **One logical change per commit.** Conventional-commit subjects (`feat:`, `fix:`, `chore:`, `refactor:`, `test:`, `docs:`, `perf:`).
24+
- **Squash-merge only.** Branch protection rejects merge commits and force-pushes to `main`.
25+
- **Tests + jacoco gate must pass.** `mvn -B -ntp clean verify` is the contract.
26+
- **Determinism is non-negotiable.** Same input → same output, byte-for-byte. Any new detector ships with a determinism test.
27+
- **Read-only serving layer.** MCP and REST API on the `serve` path do not mutate. If you find yourself adding `POST /api/<verb>` that writes, stop and reconsider.
28+
- **No secrets in code.** Repo-level GitHub Actions secrets only.
29+
30+
## Paperclip / RAN-* coordination
31+
32+
This codebase tracks work in Paperclip under the `RAN-*` prefix. When you pick up a task:
33+
34+
1. Checkout the issue (`POST /api/issues/{id}/checkout`) before you start.
35+
2. Comment progress on every heartbeat — terse markdown, link the PR.
36+
3. Branch protection requires TechLead approval; route review there.
37+
4. Reference the issue in your commit/PR body (`Closes RAN-N`).
38+
39+
If the task asks for product/feature work and `shared/runbooks/release.md` is missing on `main`, **stop**: the RAN-46 bootstrap precondition has not landed yet and product work is gated on it.
40+
41+
## Auth escalation
42+
43+
If you hit something requiring GitHub App / PAT / OAuth that the runtime cannot satisfy (org admin escalation, Sonatype Central re-namespace, OpenSSF Best Practices form, etc.), do **not** improvise auth: PATCH the issue to `blocked` with the exact ask and `@`-mention the board.

‎LICENSE‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
MIT License
22

3-
Copyright (c) 2026 RandomCodeSpace
3+
Copyright (c) 2026 Amit Kumar
44

55
Permission is hereby granted, free of charge, to any person obtaining a copy
66
of this software and associated documentation files (the "Software"), to deal

‎README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,8 @@
1212
<a href="https://github.com/RandomCodeSpace/codeiq/blob/main/LICENSE"><img src="https://img.shields.io/github/license/RandomCodeSpace/codeiq?style=flat-square&label=License" alt="MIT License"></a>
1313
<a href="https://sonarcloud.io/summary/overall?id=RandomCodeSpace_codeiq"><img src="https://sonarcloud.io/api/project_badges/measure?project=RandomCodeSpace_codeiq&metric=security_rating" alt="Security"></a>
1414
<a href="https://sonarcloud.io/summary/overall?id=RandomCodeSpace_codeiq"><img src="https://sonarcloud.io/api/project_badges/measure?project=RandomCodeSpace_codeiq&metric=reliability_rating" alt="Reliability"></a>
15+
<a href="https://api.securityscorecards.dev/projects/github.com/RandomCodeSpace/codeiq"><img src="https://api.securityscorecards.dev/projects/github.com/RandomCodeSpace/codeiq/badge" alt="OpenSSF Scorecard"></a>
16+
<a href="https://www.bestpractices.dev/projects/codeiq"><img src="https://img.shields.io/badge/OpenSSF%20Best%20Practices-pending%20registration-lightgrey?style=flat-square&logo=openssf&logoColor=white" alt="OpenSSF Best Practices (pending registration — RAN-46 AC #8)"></a>
1517
<a href="https://github.com/RandomCodeSpace/codeiq"><img src="https://img.shields.io/badge/detectors-97-brightgreen?style=flat-square&logo=codefactor&logoColor=white" alt="97 Detectors"></a>
1618
<a href="https://github.com/RandomCodeSpace/codeiq"><img src="https://img.shields.io/badge/languages-35%2B-blue?style=flat-square&logo=stackblitz&logoColor=white" alt="35+ Languages"></a>
1719
</p>

0 commit comments

Comments
 (0)