Skip to content

AGENTS.md

Latest commit

 

History

History
215 lines (173 loc) · 10.9 KB

AGENTS.md

File metadata and controls

215 lines (173 loc) · 10.9 KB
Raw

This file provides guidance when working with code in this repository.

Repository Information

Upstream Repository: https://github.com/stackrox/stackrox

Workflow

Test Failure Triaging

When a user request or prompt is prefixed with "triage" key word you must switch to the test failure triage workflow. It consists of the following steps:

  • confirm that the user request or prompt contains test failure information, if not, ask the user how to proceed
  • analyze the provided request or prompt and identify what type the test in question is
  • think hard about the root cause, present your findings to the user; do not write any code
  • ask for more information if necessary: context, logs, whatever you think might help with triaging

Committing Generated Code

When a user asks to commit a change made entirely or partially with the help of an AI agent (like yourself), you must switch to the code committing workflow. It includes the following requirements:

  • individual commits must be atomic, minimal, and group changes logically where possible
  • always include the associated user request or prompt into the commit message
  • be concise in your commit messages, briefly state the problem and the solution while focussing on what is not clear from the code itself: considered alternatives, assumptions being made, etc
  • include a note that the code was partially generated by AI

Creating Pull Requests

When creating pull requests, you must follow these requirements:

  • always create PRs as draft - use the --draft flag with gh pr create
  • this allows for review and additional changes before marking as ready for review
  • add the ai-assisted label to PRs created with AI assistance
  • PR title must follow the format enforced by .github/workflows/check-pr-title.yaml
    • read the workflow file to understand exact requirements
    • generally: conventional commit format (e.g., fix(ui): description) OR JIRA format (e.g., ROX-123: description)
    • maximum 70 characters
  • PR description must follow the template (.github/pull_request_template.md)
    • IMPORTANT: all sections, checkboxes, and structure must be preserved
    • only remove: HTML comments (<!-- -->) and placeholder text (e.g., "change me!")
    • do not remove: section headers, checkboxes, or any structural content
    • fill in all required sections and check appropriate boxes
    • be super brief and stick to facts
    • use emojis only when necessary
    • include: problem definition, considered alternatives, explain whys for chosen solution, if applicable.
    • include benchmark results if applicable

Common Development Commands

Build Commands

  • make image - Build the main StackRox container image with tag from make tag
  • make main-build-dockerized - Compile all Go binaries using Docker
  • make main-build - Build main binaries with dependency prep
  • make cli - Build and install CLI tools for all platforms
  • make cli_host-arch - Build CLI tools for current platform only
  • make all-builds - Build all components (CLI, main, UI, docs)

Testing Commands

  • make test - Run all tests (Go unit tests, UI tests, shell tests)
  • make go-unit-tests - Run Go unit tests only
  • make go-postgres-unit-tests - Run PostgreSQL integration tests (requires running Postgres on port 5432)
  • make ui-test - Run UI tests
  • make ui-component-tests - Run UI component tests
  • make shell-unit-tests - Run shell script tests

Development Commands

  • make fast-central - Quickly recompile and restart Central component
  • make fast-sensor - Quickly recompile Sensor component
  • make fast-migrator - Quickly recompile migrator component

Code Quality Commands

  • make style - Run all style checks (Go, protobuf, shell)
  • make golangci-lint - Run Go linter
  • make proto-style - Check protobuf style
  • make shell-style - Check shell script style

Code Generation Commands

  • make proto-generated-srcs - Generate Go code from protobuf definitions
  • make go-generated-srcs - Generate Go code (mockgen, stringer, easyjson)
  • make generated-srcs - Generate all source code

Adding Database Columns

When the user needs to add a new column to an existing database table:

IMPORTANT: Schema-only changes do NOT require a migration. Adding columns or tables is handled automatically by GORM AutoMigrate on every Central startup. Indexes are managed by the code generator and applied outside of GORM (see migrator/README.md). Simply update the proto definition (add field, add search/sql tags) and regenerate the schema code. A migration is ONLY needed when existing data must be backfilled or transformed. If the new column can tolerate its zero value until normal operation populates it, no migration is needed.

When a migration IS needed:

  • Read migrator/README.md for the authoritative migration workflow and examples
  • Prompt the user about their specific needs (column type, backfill requirements, performance considerations)
  • Present options based on similar migrations in migrator/migrations/ directory
  • Reference the "Code Generation Commands" section above for regenerating schema/store code
  • Suggest running code generation commands in the background if appropriate (they can be slow)
  • After code generation, run code quality checks from the "Code Quality Commands" section above

The migrator README contains detailed examples of frozen schemas, GORM usage patterns, and migration best practices.

Local Development Commands

  • roxie deploy - Deploy StackRox with roxie, also works for local clusters, see deploy/AGENTS.md for more information on roxie.
  • ./deploy/deploy-local.sh - Deploy StackRox locally (requires existing k8s cluster), still supported, but deprecated way.
  • make install-dev-tools - Install development tools (linters, generators)

Single Test Examples

  • Run specific Go test: go test -v ./central/path/to/package -run TestSpecificFunction
  • Run PostgreSQL integration tests: go test -v -tags sql_integration ./central/path/to/package
  • Testify Suite Pattern: Many tests use github.com/stretchr/testify/suite:
    • Suite tests have a top-level function like TestClient that runs the entire suite
    • Individual test methods are on a struct (e.g., func (s *ClientTestSuite) TestSomething())
    • To run the entire suite: go test ./package -run TestClient
    • To run specific subtest: go test ./package -run TestClient/TestSomething
    • WRONG: go test ./package -run TestSomething (won't find it - it's not a top-level function)

Architecture Overview

StackRox is a Kubernetes-native security platform with a distributed microservices architecture:

Core Components

  • Central (/central/) - Go-based API server, policy engine, and management hub with PostgreSQL storage
  • Sensor (/sensor/) - Go-based Kubernetes monitoring agent deployed per cluster
  • Scanner (/scanner/) - Go-based vulnerability scanning service using ClairCore
  • UI (/ui/) - React/TypeScript frontend with modern web stack
  • roxctl (/roxctl/) - Go-based CLI tool for administration and CI/CD integration
  • Operator (/operator/) - Kubernetes operator for lifecycle management

Technology Stack

  • Backend: Go (1.24.0+), PostgreSQL, gRPC/HTTP APIs, Kubernetes controllers
  • Frontend: React, TypeScript, Node.js (20.0.0+), npm
  • Infrastructure: Kubernetes-native, Helm charts, Docker/Podman containers
  • Communication: mTLS for security, gRPC for internal services, REST APIs for external access

Deployment Model

  • Central Services: Deployed in management cluster (Central, Scanner, UI, Database)
  • Secured Cluster Services: Deployed per monitored cluster (Sensor, Admission Controller)
  • Multi-cluster support: One Central instance monitors multiple Kubernetes clusters

Key Directories

  • /central/ - Central management service code
  • /sensor/ - Sensor agent code for cluster monitoring
  • /scanner/ - Vulnerability scanning service
  • /ui/ - Web frontend application
  • /roxctl/ - Command-line interface
  • /operator/ - Kubernetes operator
  • /image/ - Container image build files, Helm charts, and deployment templates
  • /generated/ - Auto-generated code from protobuf definitions
  • /proto/ - Protocol buffer definitions
  • /pkg/ - Shared Go libraries and utilities
  • /deploy/ - Deployment scripts and configurations
  • /qa-tests-backend/ - Integration tests (Groovy/Spock)

Detailed Documentation

In-code documentation: Packages with non-obvious architecture or operational gotchas often contain a markdown file (e.g. README.md) co-located with the source code. Before researching a subsystem from scratch, check for markdown files in its package directory.

When working on specific areas, refer to these detailed guides:

Operator Development:

  • operator/ARCHITECTURE.md - Internal architecture, reconciliation pipeline, and package layout
  • operator/EXTENDING_CRDS.md - How to add new fields to CRDs (Central/SecuredCluster)
  • operator/DEFAULTING.md - Defaulting mechanisms and best practices for CRD fields

Helm Chart Development:

  • image/templates/README.md - Working with Helm charts, testing, and development workflow
  • image/templates/CHART_TEMPLATING.md - Meta-templating system, feature flags, and chart instantiation
  • image/templates/CHANGING_CHARTS.md - How to add/modify Helm values fields and cluster config

When making code changes, keep this in-code documentation up-to-date.

Development

Style and Conventions

  • Go code follows golangci-lint standards
  • Additional project specific style guide in .github/go-coding-style.md
  • Protocol buffers have enforced style guidelines
  • Shell scripts are checked with shellcheck
  • UI code uses TypeScript with React conventions
  • All generated code should not be manually edited
  • Table-driven tests are defined as maps with the test name as the key.
  • Tests use assert or require provided by github.com/stretchr/testify.

Development Workflow

  1. Use make install-dev-tools to set up development environment
  2. Run make proto-generated-srcs when protobuf files change
  3. Use make fast-central or make fast-sensor for quick development iterations
  4. Run make style before committing to ensure code quality
  5. Use ./deploy/deploy-local.sh for local testing with existing k8s cluster

Environment Variables

  • STORAGE=pvc - Persist PostgreSQL data between restarts
  • SKIP_UI_BUILD=1 - Skip UI builds to speed up development
  • SKIP_CLI_BUILD=1 - Skip CLI builds to speed up development
  • DEBUG_BUILD=yes - Create debug build with debugging capabilities
  • MAIN_IMAGE_TAG - Override default image tag for deployments

Testing Notes

  • PostgreSQL integration tests require Postgres running on port 5432
  • Use docker run --rm --env POSTGRES_USER="$USER" --env POSTGRES_HOST_AUTH_METHOD=trust --publish 5432:5432 docker.io/library/postgres:15 for test setup
  • Integration tests in /qa-tests-backend/ use Groovy/Spock framework
  • Tests marked with //go:build sql_integration require database connectivity