If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/gravitational/teleport shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit today
• 49+ active contributors
• Distributed ownership (top contributor 9% of recent commits)
• AGPL-3.0 licensed
• CI configured
• Tests present
• ⚠ AGPL-3.0 is copyleft — check downstream compatibility

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live gravitational/teleport repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/gravitational/teleport.

What it runs against: a local clone of gravitational/teleport — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in gravitational/teleport | Confirms the artifact applies here, not a fork | | 2 | License is still AGPL-3.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of gravitational/teleport. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/gravitational/teleport.git
#   cd teleport
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of gravitational/teleport and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "gravitational/teleport(\\.git)?\\b" \\
  && ok "origin remote is gravitational/teleport" \\
  || miss "origin remote is not gravitational/teleport (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(AGPL-3\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"AGPL-3\\.0\"" package.json 2>/dev/null) \\
  && ok "license is AGPL-3.0" \\
  || miss "license drift — was AGPL-3.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "README.md" \\
  && ok "README.md" \\
  || miss "missing critical file: README.md"
test -f "Makefile" \\
  && ok "Makefile" \\
  || miss "missing critical file: Makefile"
test -f ".github/workflows/build-api.yaml" \\
  && ok ".github/workflows/build-api.yaml" \\
  || miss "missing critical file: .github/workflows/build-api.yaml"
test -f "Cargo.toml" \\
  && ok "Cargo.toml" \\
  || miss "missing critical file: Cargo.toml"
test -f ".golangci.yml" \\
  && ok ".golangci.yml" \\
  || miss "missing critical file: .golangci.yml"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/gravitational/teleport"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Teleport is a unified access platform that provides identity-aware connectivity, authentication, and audit across SSH, Kubernetes, databases, RDP, and cloud infrastructure without relying on long-lived credentials or VPNs. It acts as a certificate authority issuing short-lived certificates while routing traffic through secure tunnels that penetrate NATs and firewalls, giving organizations a single control plane for human and machine access. Monorepo with Go as the primary backend (~50M LOC) and TypeScript (~12M LOC) for the web UI. Core binary is a single Go executable integrating multiple protocol handlers. Rust subsystems handle RDP (lib/srv/desktop/rdp/rdpclient, lib/srv/desktop/rdp/decoder via IronRDP). Web frontend lives in web/packages/shared/libs/ironrdp. CI uses GitHub Actions with custom actions (difftest, prepare-workspace, upload-test-metrics) for test orchestration and metrics collection.

Infrastructure engineers, DevOps teams, and security architects who need to enforce single sign-on (SSO), role-based access control (RBAC), and session recording across heterogeneous infrastructure (on-prem servers, Kubernetes clusters, databases, Windows desktops, cloud APIs) without managing bastion hosts or VPNs.

Production-ready. The extensive CI/CD pipeline (50+ GitHub workflows including benchmark, e2e, integration, and flaky-test suites in .github/workflows/), large codebase (50M+ lines of Go), and structured test organization indicate a mature, actively maintained project used at scale. Regular release cycles with semantic versioning and comprehensive test coverage across multiple platforms (Linux, macOS, Windows).

Low to moderate risk. Heavy Go dependency on external crates (IronRDP from Devolutions for RDP support pinned to specific revisions), monorepo with multiple Rust workspaces (lib/srv/desktop/rdp/*) that may have independent maintenance velocity. The sheer scope (SSH, K8s, databases, RDP, web apps, Git, MCP) means breaking changes in one protocol subsystem could affect users, though AGPL-3.0 licensing and GitHub-only distribution contain risk.

Active development across multiple parallel streams: benchmark workflows (benchmark-code-root.yaml, benchmark-code-nonroot.yaml, benchmark-code-smoke-*) suggest performance optimization work; AWS e2e tests (aws-e2e-tests-non-root.yaml) and platform-specific builds (build-macos.yaml, build-windows.yaml, build-centos7-assets.yaml) indicate cross-platform hardening; flaky-test detection (flaky-tests.yaml, flaky-tests-merge-queue.yaml) is prioritized for stability.

git clone https://github.com/gravitational/teleport.git
cd teleport
make build          # Builds the main Go binary
make test           # Runs unit tests
make e2e            # Runs end-to-end tests (requires Docker/services)

Note: The Makefile (top 60 files) orchestrates builds; see Makefile and .github/actions/prepare-workspace/action.yml for dependency setup. RDP client requires Rust (lib/srv/desktop/rdp/ workspaces).

Daily commands: Development server (Auth/Proxy):

make build
./build/teleport configure -d      # Generate config
./build/teleport start              # Start all-in-one server on localhost:3025 (web), 3023 (ssh)

Web UI separately (if developing frontend):

cd web
npm install
npm start                            # Dev server typically on localhost:3000

For integration/e2e tests:

make integration    # Requires Docker and etcd (see .github/services/)
make e2e            # Full end-to-end suite

• README.md — Defines Teleport's core mission: unified access control, authentication, and audit across infrastructure (SSH, K8s, databases, RDP, APIs).
• Makefile — Entry point for building, testing, and deploying Teleport across multiple platforms and architectures.
• .github/workflows/build-api.yaml — Orchestrates API build pipeline; critical for understanding CI/CD and release automation.
• Cargo.toml — Workspace configuration for Rust components (RDP client, decoder, IronRDP integration); defines critical dependencies like IronRDP.
• .golangci.yml — Go linter configuration enforcing code quality standards across the codebase.
• api/client/alpn.go — ALPN (Application-Layer Protocol Negotiation) client logic; core to Teleport's connection routing and protocol selection.
• api/breaker/breaker.go — Circuit breaker pattern implementation protecting against cascading failures in distributed calls.

Add a new API client method

1. Define the new API method in api/client/<resource>/<resource>.go (e.g., api/client/accessrequest/access_request.go) (api/client/accessrequest/access_request.go)
2. Add corresponding unit tests in the same package (api/client/<resource>/<resource>_test.go) (api/client/accessrequest/access_request_test.go)
3. Register the client in api/client/alpn.go if it requires protocol negotiation (api/client/alpn.go)
4. Add integration test to .github/workflows/integration-tests-root.yaml or unit-tests-code.yaml (.github/workflows/integration-tests-root.yaml)

Add a new Rust component (RDP/Desktop protocol)

1. Create module in lib/srv/desktop/rdp/<component>/ directory (Cargo.toml)
2. Define Cargo.toml dependencies, preferring workspace-pinned versions from root Cargo.toml (Cargo.toml)
3. Add member to [workspace] members array in root Cargo.toml (Cargo.toml)
4. Add Rust unit tests and integrate into .github/workflows/unit-tests-rust.yaml (.github/workflows/unit-tests-rust.yaml)

Add a new CI/CD workflow

1. Create .github/workflows/my-workflow.yaml following existing patterns (e.g., unit-tests-code.yaml, e2e-tests-base.yaml) (.github/workflows/unit-tests-code.yaml)
2. Reference Makefile targets for build and test steps (Makefile)
3. Use .github/actions/prepare-workspace for environment setup (.github/actions/prepare-workspace/action.yml)
4. Add metrics upload step using .github/actions/upload-test-metrics (.github/actions/upload-test-metrics/action.yml)

Add a new linting or code quality check

1. Update .golangci.yml to add new linter rule or increase strictness (.golangci.yml)
2. If using Rust/clippy, update .github/workflows/unit-tests-rust.yaml or Cargo.toml (Cargo.toml)
3. Add pre-commit hook definition or local Makefile rule for developers (Makefile)
4. Document new rule in CONTRIBUTING.md (CONTRIBUTING.md)

• Go (primary language) — Cross-platform, static binaries, excellent concurrency model (goroutines) for handling thousands of simultaneous connections; ideal for infrastructure access control.
• Rust (RDP/desktop components) — Memory-safe systems programming for RDP protocol handling, decoder, and IronRDP integration; prevents buffer overflow vulnerabilities in wire-level protocol parsing.
• gRPC + Protocol Buffers — Efficient, language-agnostic RPC framework for internal service communication and API versioning; enables client SDKs across Go, Rust, Python, etc.
• TLS + ALPN — Single encrypted port (443/3080) with application-layer protocol negotiation routes SSH, Kubernetes, RDP, databases without separate ports or multiplexing logic.
• Circuit Breaker pattern — Prevents cascading failures when downstream services (auth, resource services) become unavailable; critical for cluster stability under load.

• Single binary with embedded auth, SSH, Kubernetes, database, RDP, and web UI

  • Why: Simplifies deployment and reduces operational overhead; users run one daemon instead of multiple services.
  • Consequence: Larger binary size (~100MB+); tightly coupled components make selective feature disabling complex.

• ALPN-based protocol routing on a single port instead of separate ports for each protocol

  • Why: Reduces firewall rule complexity and operator burden; single port is easier to expose.
  • Consequence: Requires stateful connection handling and protocol negotiation logic; harder to debug if ALPN negotiation fails.

• Go for API/services + Rust for RDP/desktop protocols

  • Why: Leverages IronRDP (battle-tested Rust RDP implementation) for security; Go handles fast iteration and operational tooling.
  • Consequence: Polyglot repo requires Rust and Go expertise; FFI or serialization overhead between Go orchestration and Rust RDP processing.

• Monorepo structure (single repo for CLI, server, API, UI, docs, infrastructure)

  • Why: Atomic commits for coordinated releases; single source of truth for all Teleport components.
  • Consequence: Large repo (~600 files); slower clone/CI on full codebase; potential merge conflicts across teams.

• Does not handle identity provider (IdP) authentication directly; delegates to external OIDC, SAML, GitHub, GitLab providers
• Not a VPN or bastion host replacement; Teleport is an identity and access control layer that tunnels traffic, not a general VPN
• Does not provide storage-level encryption for databases; enforces access control and audit before traffic reaches the database
• Not a configuration management system (no IaC state management); Teleport controls access, not infrastructure deployment

etcd dependency: Integration and e2e tests require etcd running (see .github/services/Dockerfile.etcd); local setup may fail silently if etcd is not available. RDP requires Rust toolchain: Building lib/srv/desktop/rdp/ requires cargo and Rust compiler; Go build alone skips RDP features. IronRDP pinned revision: lib/srv/desktop/rdp/decoder depends on a specific IronRDP git revision (a0a3e750c9e4ee9c73b957fbcb26dbc59e57d07d); updating requires careful coordination. Root vs non-root tests: Some tests (aws-e2e-tests-non-root.yaml, benchmark-code-nonroot.yaml) deliberately run unprivileged; others require root; CI matrix covers both but local runs may skip critical tests. Web UI dev server separate from backend: localhost:3000 (npm) proxies to localhost:3025 (Go server); misconfigured CORS or proxy settings break development. Workspace configuration: Rust workspace defined in Cargo.toml workspace members (lib/srv/desktop/rdp/rdpclient, decoder, web/packages/shared/libs/ironrdp); modifying workspace structure requires careful sync with CI.

• Short-lived certificates — Core Teleport security model: CA in lib/auth/ issues time-bound SSH/TLS certs instead of storing passwords; understanding cert rotation, revocation, and renewal is essential for auth subsystem work

• hashicorp/boundary — Similar access proxy and session recording for heterogeneous infrastructure; direct competitor solving SSH/RDP/database access without Teleport's integrated CA and SSO focus
• open-telemetry/opentelemetry-go — Teleport uses OpenTelemetry for distributed tracing and observability; understanding OTel patterns is essential for reading lib/auth/ and lib/srv/ telemetry hooks
• kubernetes-sigs/controller-runtime — Teleport's Kubernetes integration (lib/kube/) follows Kubernetes patterns and client-go; understanding controller patterns helps navigate the K8s subsystem
• devolutions/ironrdp — External Rust dependency pinned in Cargo.toml (workspace.dependencies); source of RDP protocol implementation for lib/srv/desktop/rdp/
• gravitational/gravity — Sibling project by same author; Kubernetes distribution platform that integrates with Teleport for access control; shows real-world Teleport deployment patterns

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add CI workflow for Rust RDP client integration tests

The repo has Rust workspace members for RDP (rdpclient, decoder, ironrdp) but no dedicated CI workflow for Rust tests despite having unit-tests-rust.yaml. A new workflow should run Rust tests specifically for the desktop/rdp modules with coverage reporting, similar to how unit-tests-code.yaml handles Go. This ensures RDP protocol changes don't regress.

• [ ] Review existing .github/workflows/unit-tests-rust.yaml to understand current Rust CI setup
• [ ] Examine lib/srv/desktop/rdp/ structure and Cargo.toml dependencies for test requirements
• [ ] Create new workflow .github/workflows/unit-tests-rdp.yaml that runs 'cargo test' for rdpclient, decoder, and ironrdp packages
• [ ] Add coverage collection via tarpaulin or similar for RDP Rust crates
• [ ] Configure workflow to trigger on changes to lib/srv/desktop/rdp/** and web/packages/shared/libs/ironrdp/
• [ ] Add PR status check to .github/CODEOWNERS for RDP-related reviews

Add Windows Desktop RDP feature documentation and test plan template

The repo has test plan templates for identity, security, and web (see .github/ISSUE_TEMPLATE/), but no dedicated template for RDP/Windows Desktop features. With IronRDP integration and desktop/rdp modules present, contributors lack guidance on testing RDP protocol changes, clipboard handling, graphics rendering, and audio channels.

• [ ] Create .github/ISSUE_TEMPLATE/test-plan-rdp.md template mirroring test-plan-identity-security.md structure
• [ ] Include sections for RDP protocol versions tested, Windows OS compatibility, graphics/audio/clipboard edge cases, and regression scenarios
• [ ] Add corresponding documentation file docs/rdp-testing-guide.md explaining RDP test infrastructure (ironrdp dependencies, decoder tests)
• [ ] Reference the new template in CONTRIBUTING.md guidelines for RDP-related PRs
• [ ] Add test plan template to config.yml ISSUE_TEMPLATE configuration

Consolidate and add missing GitHub Actions for Rust workspace crate builds

The Cargo.toml workspace defines multiple Rust crate members but CI coverage is incomplete. There's no dedicated build-api.yaml equivalent for verifying all workspace members compile correctly with release optimizations. This is risky since ironrdp-* dependencies are pinned to specific git revisions and breaking changes could silently merge.

• [ ] Review .github/workflows/build-api.yaml to understand Go build validation pattern
• [ ] Create .github/workflows/build-rust-workspace.yaml that runs 'cargo build --release' for all workspace members with specified Cargo.lock lockfile verification
• [ ] Add clippy linting and fmt checks for Rust codebase consistency across lib/srv/desktop/rdp/ and web/packages/shared/libs/ironrdp/
• [ ] Configure to run on Cargo.toml, Cargo.lock, and rust source file changes
• [ ] Add job to validate ironrdp-* git revision pins haven't diverged (comparing against latest main of Devolutions/IronRDP)
• [ ] Add status check requirement in branch protection rules

• Add integration tests for the PostgreSQL database access handler in lib/srv/db/postgres/; currently lacks test coverage for protocol parsing and session recording in lib/srv/db/postgres/protocol.go.
• Improve error messages in lib/client/client.go when SSH key negotiation fails; currently returns generic 'authentication failed' instead of specific cipher/key exchange mismatches that would help users debug issues.
• Add TypeScript type definitions for the RDP client API in web/packages/shared/libs/ironrdp; currently the integration between web UI and Rust RDP decoder lacks full type safety, causing runtime errors in session management.

• High · Pinned External Dependency with Fixed Revision — Cargo.toml - [workspace.dependencies] ironrdp-* entries. The Cargo.toml workspace dependencies pin IronRDP crates to a specific Git revision (a0a3e750c9e4ee9c73b957fbcb26dbc59e57d07d). While pinning can be good for reproducibility, this approach may delay security patches from upstream. If vulnerabilities are discovered in IronRDP, the project won't automatically receive fixes unless the revision is manually updated. Fix: Implement a dependency update strategy: 1) Use tools like Dependabot or Renovate (already present in .github/renovate.json) to automatically check for updates, 2) Establish a schedule to review and test IronRDP updates, 3) Consider using a version range constraint instead of fixed revision if appropriate, 4) Monitor IronRDP's security advisories closely.
• High · Incomplete Dependency Analysis - Truncated Cargo.toml — Cargo.toml - incomplete file content. The provided Cargo.toml content is truncated (ends mid-line at 'ironrdp-tls'), making it impossible to perform a complete security audit of all workspace dependencies. Additional dependencies, their versions, and potential vulnerabilities cannot be assessed. Fix: Provide the complete Cargo.toml file for full dependency security analysis. Ensure all dependencies are reviewed for known vulnerabilities using: 1) cargo audit to check for known CVEs, 2) cargo tree to understand dependency trees, 3) Regular scanning with tools like Trivy (present in .trivyignore), 4) SBOM generation for supply chain security.
• Medium · Potential Git-based Dependency Supply Chain Risk — Cargo.toml - All ironrdp-* dependencies using git= protocol. Multiple dependencies are sourced directly from GitHub repositories (Devolutions/IronRDP) rather than crates.io registry. While Git dependencies offer flexibility, they bypass the crates.io security review process and registry signing mechanisms. An attacker could potentially compromise the GitHub repository or perform MITM attacks. Fix: 1) Verify the IronRDP repository is owned and maintained by trusted parties, 2) Enable GitHub branch protection and require code reviews, 3) Consider mirroring critical dependencies internally, 4) Use git commit signing verification, 5) Implement SCA (Software Composition Analysis) tools, 6) Consider using crates.io versions once they're available.
• Medium · License Compliance - AGPL-3.0-only Constraint — Cargo.toml - [workspace.package] license field. The workspace is configured with AGPL-3.0-only license, which has strong copyleft obligations. Integrating proprietary or incompatible licensed code could create compliance issues. The presence of IronRDP (likely MIT/Apache-2.0 licensed) requires verification of license compatibility. Fix: 1) Audit all transitive dependencies for license compatibility with AGPL-3.0, 2) Document license decisions for commercial distributions, 3) Consider license scanning tools (e.g., FOSSA, Black Duck), 4) Review private release policy in SECURITY.md for IP considerations, 5) Consult legal team for proprietary distributions.
• Medium · Debug Symbols in Release Builds — Cargo.toml - [profile.release] section. The release profile in Cargo.toml is configured with 'debug = 1', which includes debug information in release binaries. This increases binary size and could leak information about code structure and variable names to attackers if binaries are leaked or compromised. Fix: 1) Set 'debug = 0' or 'strip = true' for release builds to remove debug symbols, 2) If debugging is needed in production, separate debug symbols into .dbg files, 3) Implement secure symbol storage separate from distribution binaries, 4) Document the rationale if debug info is intentionally retained.
• Low · Incomplete Security Policy Documentation — SECURITY.md - Incomplete file content after 'customers have had time to'. The SECURITY.md file content is truncated, with the private release policy explanation cut off. This incomplete documentation could confuse users about the project's vulnerability disclosure process and may not provide sufficient guidance for responsible disclosure. Fix: 1) Complete the SECURITY.md documentation with full private release policy details, 2) Specify embargoed disclosure timelines

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.