Skip to content

Commit 407c2de

Browse files
migmartriclaude
migmartri
and
claude
committed
feat: add comprehensive CLAUDE.md development guide
Add detailed documentation for Claude Code instances working with the Chainloop codebase: - Complete architecture breakdown for all three components (Control Plane, Artifact CAS, CLI) - Detailed development environment setup with Docker Compose configurations - Component-specific development workflows and patterns - Build, test, and lint command reference - Database migration and code generation workflows - Development credentials and authentication setup - Integration testing guidance and troubleshooting - Third-party plugin integration system overview This provides comprehensive guidance for future Claude Code instances to effectively work with this complex Supply Chain Security platform. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com> Signed-off-by: Miguel Martinez <miguel@chainloop.dev>
1 parent b00fbfc commit 407c2de

1 file changed

Lines changed: 254 additions & 0 deletions

File tree

‎CLAUDE.md‎

Lines changed: 254 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,254 @@
1+
# CLAUDE.md
2+
3+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4+
5+
## Overview
6+
7+
Chainloop is an open-source evidence store for Software Supply Chain attestations, SBOMs, VEX, SARIF, and other compliance artifacts. The project consists of three main components: a Control Plane (server), Artifact Content Addressable Storage (CAS), and a CLI client.
8+
9+
## Architecture
10+
11+
The codebase follows a microservices architecture with three main components and shared libraries:
12+
13+
### Control Plane (`app/controlplane/`)
14+
Main backend service implementing hexagonal architecture:
15+
- **API Layer** (`./api/`): Protobuf definitions and generated gRPC/HTTP services
16+
- **Server Layer** (`./internal/server`): HTTP/gRPC servers, middlewares, and request handling
17+
- **Service Layer** (`./internal/service`): Protocol buffer service implementations
18+
- **Business Layer** (`./pkg/biz`): Core business logic and repository abstractions
19+
- Organizations, workflows, attestations, API tokens, groups, projects
20+
- CAS backend management, integrations, user access control
21+
- Policy evaluation and referrer management
22+
- **Data Layer** (`./pkg/data`): Repository implementations using Ent ORM
23+
- PostgreSQL with Atlas migrations in `./pkg/data/ent/migrate/migrations/`
24+
- Ent schemas in `./pkg/data/ent/schema/`
25+
26+
**Dependencies**: OIDC provider, PostgreSQL, Secret storage (Vault/AWS/GCP/Azure), Artifact CAS
27+
**Authentication**: JWT tokens, OIDC delegation, RBAC with Casbin
28+
**Key Features**: Multi-tenancy, workflow contracts, policy as code, audit logging
29+
30+
### Artifact CAS (`app/artifact-cas/`)
31+
Content Addressable Storage proxy service:
32+
- **API Layer** (`./api/`): gRPC bytestream protocol for efficient streaming
33+
- **Server Layer** (`./internal/server`): gRPC server setup and middlewares
34+
- **Service Layer** (`./internal/service`): Bytestream, download, resource, and status services
35+
- **Storage Backends** (`pkg/blobmanager/`): OCI registry, S3, Azure Blob Storage
36+
- Content-addressable storage with SHA256 digests
37+
- Multi-tenant through runtime credential selection
38+
- Immutable artifact storage with digest verification
39+
40+
**Dependencies**: Secret storage backend for OCI/blob credentials
41+
**Authentication**: JWT tokens with upload/download permissions from Control Plane
42+
**Key Features**: Multi-backend support, streaming uploads/downloads, content verification
43+
44+
### CLI (`app/cli/`)
45+
Command-line client for both operators and CI/CD systems:
46+
- **Commands** (`./cmd/`): Cobra-based command structure
47+
- `attestation_*`: Attestation crafting lifecycle (init, add, push, status, verify)
48+
- `workflow_*`: Workflow and contract management
49+
- `organization_*`: Organization and membership operations
50+
- `artifact_*`: Artifact upload/download operations
51+
- `auth_*`: Authentication and account management
52+
- **Actions** (`./internal/action/`): Business logic implementations for each command
53+
- **Policy Development** (`./internal/policydevel/`): Local policy development and testing
54+
- **Telemetry** (`./internal/telemetry/`): Usage analytics with PostHog
55+
56+
**Key Features**: OIDC authentication, multi-environment config, plugin system, attestation crafting
57+
58+
### Shared Libraries (`pkg/`)
59+
Common functionality across components:
60+
- **Attestation** (`pkg/attestation/`):
61+
- **Crafter**: Attestation creation with material collection and runner context
62+
- **Materials**: Support for 25+ evidence types (SBOM, SARIF, VEX, OCI images, etc.)
63+
- **Runners**: CI/CD platform integration (GitHub Actions, GitLab, Azure, Jenkins, etc.)
64+
- **Signer**: Chainloop, Cosign, SignServer integration
65+
- **Verifier**: Attestation verification and timestamp validation
66+
- **Policies** (`pkg/policies/`): OPA/Rego policy evaluation engine
67+
- **Blob Manager** (`pkg/blobmanager/`): Multi-backend storage abstraction
68+
- **Credentials** (`pkg/credentials/`): Secret management for multiple providers
69+
- **gRPC Connection** (`pkg/grpcconn/`): Reusable gRPC client setup
70+
71+
## Development Commands
72+
73+
### Initial Setup
74+
```bash
75+
make init # Install required development tools
76+
```
77+
78+
### Building
79+
```bash
80+
# Root level - build all components
81+
make all # Generate APIs and protobuf bindings
82+
make api # Generate API proto bindings
83+
make generate # Generate code, APIs, configs
84+
85+
# Individual components
86+
make -C app/controlplane build
87+
make -C app/cli build
88+
make -C app/artifact-cas build
89+
```
90+
91+
### Testing
92+
```bash
93+
# Root level
94+
make test # Run all tests
95+
96+
# Component-specific
97+
make -C app/controlplane test # All tests including integration
98+
make -C app/controlplane test-unit # Unit tests only (SKIP_INTEGRATION=true)
99+
make -C app/cli test
100+
make -C app/artifact-cas test
101+
```
102+
103+
### Linting
104+
```bash
105+
# Root level - lint all components
106+
make lint
107+
108+
# Component-specific
109+
make -C app/controlplane lint # golangci-lint + buf lint
110+
make -C app/cli lint
111+
make -C app/artifact-cas lint
112+
```
113+
114+
### Development Server
115+
```bash
116+
# Start auxiliary services (PostgreSQL, Vault, Dex OIDC)
117+
cd devel && docker compose up
118+
119+
# Run components (in separate terminals)
120+
make -C app/controlplane run # Runs migration_apply first
121+
make -C app/artifact-cas run
122+
123+
# CLI usage
124+
go run app/cli/main.go --insecure [command]
125+
```
126+
127+
### Database Operations
128+
```bash
129+
cd app/controlplane
130+
make migration_apply # Apply migrations to local DB
131+
make migration_sync # Sync migrations with Ent schema
132+
make migration_new # Create empty migration file
133+
make migration_lint # Lint migration files
134+
```
135+
136+
## Key Technologies
137+
138+
- **Language**: Go 1.24.4
139+
- **API**: gRPC with HTTP/JSON gateway, Protocol Buffers with buf
140+
- **Database**: PostgreSQL with Ent ORM, Atlas for migrations
141+
- **Authentication**: OIDC, JWT tokens
142+
- **Policy**: Open Policy Agent (OPA) with Rego
143+
- **Storage**: Multi-backend (OCI, S3, Azure Blob, inline)
144+
- **Cryptography**: Sigstore (Cosign, Fulcio), in-toto attestations
145+
- **Standards**: SLSA, SBOM (SPDX/CycloneDX), SARIF, OpenVEX, CSAF
146+
147+
## Development Environment
148+
149+
### Setup Options
150+
151+
**Option 1: Local Development (Recommended)**
152+
```bash
153+
# 1. Install tools
154+
make init
155+
156+
# 2. Start auxiliary services
157+
cd devel && docker compose up
158+
159+
# 3. Run components locally (separate terminals)
160+
make -C app/controlplane run
161+
make -C app/artifact-cas run
162+
163+
# 4. Configure CLI
164+
go run app/cli/main.go config save --insecure --control-plane localhost:9000 --artifact-cas localhost:9001
165+
go run app/cli/main.go --insecure auth login
166+
```
167+
168+
**Option 2: Containerized Labs Environment**
169+
```bash
170+
# 1. Add dex hostname to /etc/hosts
171+
echo "127.0.0.1 dex" | sudo tee -a /etc/hosts
172+
173+
# 2. Run full containerized stack
174+
docker compose -f devel/compose.labs.yml up
175+
176+
# 3. Extract development token from logs
177+
docker compose -f devel/compose.labs.yml logs control-plane | grep "DEVELOPMENT USER TOKEN" -A 1
178+
179+
# 4. Authenticate with token
180+
chainloop --insecure auth login --skip-browser
181+
```
182+
183+
### Development Infrastructure
184+
185+
**Compose Configuration**:
186+
- `compose.common.yml`: PostgreSQL 16 + Vault (in-memory dev mode)
187+
- `compose.yml`: Adds Dex OIDC for local development
188+
- `compose.labs.yml`: Full containerized environment with pre-built images
189+
190+
**Development Services**:
191+
- **PostgreSQL**: `localhost:5432`, database: `controlplane`, user: `postgres`, no password
192+
- **Vault**: `localhost:8200`, dev token: `notasecret` (in-memory, data lost on restart)
193+
- **Dex OIDC**: `localhost:5556`, static users with password `"password"`
194+
- **Control Plane**: `localhost:9000` (gRPC) / `localhost:8000` (HTTP)
195+
- **Artifact CAS**: `localhost:9001` (gRPC) / `localhost:8001` (HTTP)
196+
- **Optional Minio S3**: `localhost:9002` (API) / `localhost:9003` (Console) with `--profile optional`
197+
198+
**Development Credentials**:
199+
- **OIDC Users**: `sarah@chainloop.local` / `john@chainloop.local` (password: `password`)
200+
- **Signing Keys**: Development keypairs in `devel/devkeys/` (DO NOT USE IN PRODUCTION)
201+
- `ca.pem`/`ca.pub`: Certificate Authority
202+
- `cas.pem`/`cas.pub`: Artifact CAS signing
203+
- `freetsa.pem`: Free TSA timestamp authority
204+
- Self-signed certificates in `devkeys/selfsigned/`
205+
206+
## Testing Environment
207+
208+
- **Integration Tests**: Use testcontainers for isolated database testing
209+
- **Unit Tests**: Run with `make test-unit` or `SKIP_INTEGRATION=true make test`
210+
- **Local PostgreSQL**: `postgres://postgres:@localhost:5432/controlplane?sslmode=disable`
211+
- **macOS Docker Fix**: `sudo ln -s $HOME/.docker/run/docker.sock /var/run/docker.sock`
212+
213+
## Code Generation
214+
215+
The project heavily uses code generation:
216+
- **Protobuf**: API definitions and gRPC services
217+
- **Wire**: Dependency injection
218+
- **Ent**: ORM models and queries
219+
- **Buf**: Protobuf tooling and validation
220+
221+
Always run `make generate` after modifying .proto files or Ent schemas.
222+
223+
## Contract-Based Development
224+
225+
Workflow Contracts define the structure and requirements for CI/CD attestations. They specify what materials must be collected and policies that must be evaluated.
226+
227+
## Component-Specific Development
228+
229+
### Control Plane Development
230+
- **Schema Changes**: Update Ent schemas in `pkg/data/ent/schema/`, then run `make generate && make migration_new && make migration_apply`
231+
- **API Changes**: Modify `.proto` files, then run `make api` to regenerate code
232+
- **Business Logic**: Implement in `pkg/biz/` layer with repository interfaces
233+
- **Tests**: Unit tests with `make test-unit`, integration tests with `make test` (uses testcontainers)
234+
235+
### CLI Development
236+
- **Commands**: Add new commands in `cmd/` following Cobra patterns
237+
- **Actions**: Implement business logic in `internal/action/`
238+
- **Policy Development**: Use `internal/policydevel/` for local policy testing
239+
- **Default Endpoints**: Override with `-ldflags` at build time using `defaultCASAPI` and `defaultCPAPI` variables
240+
241+
### Artifact CAS Development
242+
- **Storage Backends**: Implement new backends in `pkg/blobmanager/` with Provider interface
243+
- **Authentication**: JWT tokens generated by Control Plane, validated by CAS
244+
- **Streaming**: Uses gRPC bytestream protocol for efficient file transfers
245+
246+
## Commit Guidelines
247+
248+
All commits must meet these criteria:
249+
- **Signed**: Use `-S` flag ([signing guide](https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits))
250+
- **Developer Certificate of Origin**: Use `--sign-off` flag
251+
- **Conventional Commits**: Follow [format guidelines](https://www.conventionalcommits.org/en/v1.0.0)
252+
- **Example**: `git commit -S -s -m "feat: add new material type"`
253+
254+
Code reviews are required for all submissions via GitHub pull requests.

0 commit comments

Comments
 (0)