Skip to content

AGENTS.md

Latest commit

 

History

History
178 lines (144 loc) · 8.81 KB

AGENTS.md

File metadata and controls

178 lines (144 loc) · 8.81 KB

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

Local Development Commands

  • ./deploy/deploy-local.sh - Deploy StackRox locally (requires existing k8s cluster)
  • 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

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

Operator Development:

  • 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

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

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