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/TencentBlueKing/bk-cmdb 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.

WAIT — Mixed signals — read the receipts

• Last commit 1w ago
• 8 active contributors
• Distributed ownership (top contributor 34% of recent commits)
• Other licensed
• ⚠ Non-standard license (Other) — review terms
• ⚠ No CI workflows detected
• ⚠ No test directory detected

_{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 TencentBlueKing/bk-cmdb repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/TencentBlueKing/bk-cmdb.

What it runs against: a local clone of TencentBlueKing/bk-cmdb — 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 TencentBlueKing/bk-cmdb | Confirms the artifact applies here, not a fork | | 2 | License is still Other | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | Last commit ≤ 39 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of TencentBlueKing/bk-cmdb. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/TencentBlueKing/bk-cmdb.git
#   cd bk-cmdb
#
# 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 TencentBlueKing/bk-cmdb and re-run."
  exit 2
fi

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

# 2. License matches what RepoPilot saw
(grep -qiE "^(Other)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Other\"" package.json 2>/dev/null) \\
  && ok "license is Other" \\
  || miss "license drift — was Other 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"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 39 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~9d)"
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/TencentBlueKing/bk-cmdb"
  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).

BlueKing CMDB (Configuration Management Database) is an enterprise-grade asset and application configuration management platform built in Go with a Vue.js web UI. It provides topology-based host management, custom data models, process management, event push mechanisms, and audit trails—serving as the single source of truth for infrastructure inventory across on-prem and cloud environments in large organizations. Monolithic Go backend (likely in src/ or main package directories based on file structure) with Vue.js frontend for UI, layered as: atomic resource operations (hosts, processes, objects) → scenario layer (composite operations) → API gateway layer. API docs (docs/apidoc/apigw/) expose endpoints; database schema documented in docs/db/. CI automation via .github/workflows and Makefile-based builds.

DevOps engineers, infrastructure teams, and system administrators at enterprises (especially Tencent ecosystem users) who need to manage thousands of hosts, services, and custom business objects with fine-grained permissions, automated discovery, and change event notifications.

Production-ready and actively maintained. Currently at v3.2.19 with regular releases; the repository shows active development with CI/CD pipelines via BK DevOps, extensive API documentation, and deployment guides for Kubernetes. Master branch carries a stability warning, so users should use tagged releases.

Low to moderate risk for enterprise adoption but check: (1) primarily designed for Tencent BlueKing ecosystem integration—deployment outside that context requires careful config, (2) large Go monolith (~11.5MB of Go code) means compile times and build complexity, (3) database schema complexity (documented in docs/db/) requires careful migration planning during upgrades.

Active feature development around Kubernetes resource management (batch_create_kube_, batch_update_kube_ endpoints visible in docs), cache optimization (full_sync_cond_for_cache APIs), and audit/compliance features (find_audit_by_id, list_operation_audit). Version progression from 3.2.x suggests incremental refinements rather than major rearchitecture.

Clone: git clone https://github.com/TencentBlueKing/bk-cmdb.git && cd bk-cmdb. Build: make (Makefile present). For quick experience: docker-compose via docs/wiki/container-support.md or Helm: helm install using docs/support-file/helm/. Full compile instructions in docs/overview/source_compile.md.

Daily commands: After make, binaries likely output to bin/. Start via: ./bin/cmdb-server (or equivalent). Frontend dev: npm install && npm run dev (inferred from Vue presence). See docs/overview/installation.md for full deployment steps including database initialization and config setup.

• docs/overview/architecture.md: Defines the three-layer architecture (atomic ops, scenario, API) that structures all backend code organization
• docs/db/README.md: Documents complete database schema and relationships—critical for understanding data model constraints before modifying any business logic
• docs/apidoc/apigw/backend/bk_apigw_resources_bk-cmdb.yaml: API Gateway resource definition; shows all exposed endpoints and their contracts—essential reference for backend API changes
• docs/overview/code_framework.md: Maps code directory structure to functional areas, saving hours of exploration in a large monolith
• Makefile: Build automation; reveals compilation flags, output paths, and local testing procedures
• .github/pull_request_template.md: Submission requirements and review criteria specific to this project's governance

New API endpoint: Add handler in main Go service code, register in API gateway layer (docs/apidoc/apigw/ shows endpoint structure). New model/field: Update schema in database layer (docs/db/), add validation and migration. UI feature: Add Vue component in frontend src/, register in router. Custom permissions: Modify RBAC rules in permission management subsystem. Start with docs/CONTRIBUTING.md and docs/overview/code_framework.md.

Database-first design: CMDB schema is intricate (docs/db/) and tightly coupled to code—schema changes must be backward-compatible and include migration scripts. BlueKing integration: Deployment assumes integration with BlueKing PaaS authentication and API gateway; standalone setup requires disabling BK-specific features (check .code.yml and docs/overview/installation.md for config keys). Large initial data load: Hosts and topology data can be massive; cache layer (full_sync_cond_for_cache endpoints) is not optional in production. Go module management: Dependency versions not visible in file list—check go.mod for potential supply-chain issues. Vue build: Frontend bundling tied to specific Node/npm versions; documented in package.json (not shown here).

• Atomic Operations Layer — CMDB abstracts all resource mutations (create/update/delete for hosts, processes, objects) into an atomic ops layer before exposing them via scenario/API layers—understanding this layering is essential to avoid bypassing validation or audit hooks when adding features
• Custom Data Model — Unlike rigid CMDBs, CMDB allows runtime definition of custom object types and relationships beyond built-in host/process/business models—critical for enterprises needing to model network, middleware, or domain-specific assets
• Topology-Based Hierarchies — Resources are organized in a directed acyclic graph (business → cluster → module → host) rather than flat tables; query logic must respect hierarchy constraints and permission boundaries at each level
• Event-Driven Push Architecture — CMDB doesn't just store state—it pushes change events via callbacks to downstream systems (BK-CI, BK-SOPS, etc.); feature changes must account for event schema versioning and delivery guarantees
• Role-Based Access Control (RBAC) — Permissions are user-group and resource-instance scoped; operations must check RBAC before returning data or allowing mutations—cannot simply add a new API without tying it to the RBAC matrix
• Machine Data Snapshots — CMDB captures periodic snapshots of host configuration (CPU, memory, network) for change tracking and historical analysis—snapshot schema and collection timing are separate from live host state and require careful consistency management
• Cache Layer with Full-Sync Conditions — Large-scale deployments use a dedicated cache (visible in full_sync_cond_for_cache and list_cached_* endpoints) to avoid expensive topology queries; understanding cache invalidation and resync conditions is crucial for performance troubleshooting

• TencentBlueKing/bk-PaaS — CMDB depends on BlueKing PaaS for authentication, SaaS hosting, and API gateway routing; often deployed as a BK SaaS application
• TencentBlueKing/bk-bcs — BCS (container platform) consumes CMDB Kubernetes resources (batch_create_kube_* endpoints) for topology sync and resource discovery
• TencentBlueKing/bk-sops — SOPS (workflow engine) queries CMDB for host/business topology to populate task variables and execution targets
• TencentBlueKing/bk-ci — BK-CI uses CMDB host/cluster data for build agent allocation and deployment target selection
• netbox/netbox — Open-source DCIM alternative with similar topology and custom object modeling; useful for evaluating feature parity or migration strategies

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 comprehensive API documentation for Chinese (zh) endpoints with examples and error codes

The repo has extensive API documentation split between English (docs/apidoc/apigw/backend/en/) and Chinese (docs/apidoc/apigw/backend/zh/), but the Chinese documentation appears incomplete compared to the API gateway resource definition (docs/apidoc/apigw/backend/bk_apigw_resources_bk-cmdb.yaml). Adding detailed request/response examples, error code explanations, and practical use cases for the 30+ Kubernetes and host management APIs would significantly improve usability for Chinese-speaking contributors and users.

• [ ] Review docs/apidoc/apigw/backend/bk_apigw_resources_bk-cmdb.yaml to identify all API endpoints
• [ ] Compare against docs/apidoc/apigw/backend/zh/ directory to find missing or incomplete endpoint documentation
• [ ] Add request/response JSON examples for at least 10 critical endpoints (batch_create_kube_*, search_hostidentifier, etc.)
• [ ] Document common error codes and troubleshooting steps for each API category
• [ ] Ensure parity between docs/apidoc/apigw/backend/en/ and zh/ directories

Create GitHub Actions workflow for API documentation validation

The repository has extensive API documentation in YAML and Markdown formats (docs/apidoc/) but no automated validation. A CI workflow should validate that the YAML schema in docs/apidoc/apigw/backend/bk_apigw_resources_bk-cmdb.yaml matches referenced Markdown documentation files and checks for broken links between English/Chinese docs.

• [ ] Create .github/workflows/api-docs-validate.yml workflow file
• [ ] Implement schema validation for docs/apidoc/apigw/backend/bk_apigw_resources_bk-cmdb.yaml using a YAML linter
• [ ] Add check to ensure every API endpoint in YAML has corresponding .md documentation in both en/ and zh/ directories
• [ ] Validate Markdown links don't reference non-existent files
• [ ] Run on pull requests that modify files in docs/apidoc/

Implement CONTRIBUTING.md guidelines for API documentation updates with templates

While docs/CONTRIBUTING.md exists, there's no specific guidance for contributors adding or modifying API documentation. The repository has complex API patterns (Kubernetes resources, cache operations, audit trails) that require consistent documentation. Creating templates and guidelines would reduce friction for new contributors and ensure quality API docs.

• [ ] Expand docs/CONTRIBUTING.md with an 'API Documentation' section
• [ ] Create a reusable template file (.github/api-doc-template.md) with required sections: endpoint description, parameters, response format, error codes, and example requests
• [ ] Document the relationship between docs/apidoc/apigw/backend/bk_apigw_resources_bk-cmdb.yaml and .md files
• [ ] Add checklist for PR reviewers to validate API documentation quality
• [ ] Include examples using actual endpoints from the CMDB API (e.g., batch_create_kube_pod, search_hostidentifier)

• Add unit test coverage for atomic resource operation layer functions (src/ or equivalent Go paths)—currently no test files visible in top 60; start with single resource type (e.g., host CRUD).
• Document missing Kubernetes API fields in docs/apidoc/backend/en/batch_create_kube_pod.md and related k8s endpoints—compare with actual Go struct tags in code to fill schema gaps.
• Create a migration guide from on-prem CMDB v2.x to v3.2.19 in docs/ (currently only docs/overview/upgrade-from-ce.md exists for community → open-source); add specific SQL migration steps from docs/db/ schema diffs.

The bk-cmdb repository shows an enterprise-grade configuration management system with proper documentation structure, but a comprehensive security assessment is severely limited by missing critical analysis inputs: no dependency manifests, no actual source code content, and no Docker/infrastructure configurations. Based on available metadata, the project appears to follow some security best practices (MIT licensing, organized code structure), but vulnerabilities cannot be comprehensively identified without access to: (1) dependency files for SCA, (2) source code for SAST, and (3) infrastructure configurations. The security score reflects this incomplete analysis. Critical next steps: obtain full dependency manifests, provide representative source code samples, and include Docker/Kubernetes configurations for complete security assessment.

• Medium · Missing Dependency File Analysis — Project root - package.json, requirements.txt, go.mod, or equivalent. The dependency/package file content was not provided for analysis. This prevents comprehensive identification of insecure or outdated dependencies that may contain known vulnerabilities (e.g., npm packages, Python packages, Go modules). Fix: Provide complete dependency manifests for security scanning. Use tools like: npm audit, pip-audit, go list -json, or OWASP Dependency-Check to identify vulnerable dependencies.
• Medium · Incomplete Docker/Infrastructure Configuration Visibility — Dockerfile, docker-compose.yml, kubernetes manifests (not provided). Docker configuration and security context details are not provided. Cannot assess for: exposed ports, missing resource limits, insecure image bases, missing security contexts, or privilege escalation risks. Fix: Provide Docker and infrastructure configuration files for analysis. Implement: minimal base images, non-root users, resource limits, network policies, and security scanning in CI/CD.
• Low · API Documentation Exposure — docs/apidoc/apigw/backend/ directory structure. Extensive API documentation is included in the repository (docs/apidoc/apigw/backend/). While documentation is valuable, detailed API specifications in version control may aid attackers in reconnaissance if the repository is public. Fix: Consider hosting sensitive API documentation on authenticated platforms separate from public source repositories, or implement rate limiting and API authentication documentation warnings.
• Low · Source Code Analysis Limited by File Content — All source files (Go, Python, JavaScript code not provided). Only directory structure and README were provided without actual source code content. Cannot perform static analysis for: SQL injection, XSS, path traversal, CSRF, authentication flaws, cryptographic weaknesses, or other code-level vulnerabilities. Fix: Provide actual source code for comprehensive SAST analysis. Use tools like: SonarQube, Checkmarx, Bandit (Python), GoSec (Go), ESLint with security plugins (JavaScript).
• Low · License File Present - Good Practice — LICENSE.txt. MIT license detected (LICENSE.txt), which is positive for open source transparency, but ensure license compliance in dependencies is verified. Fix: Regularly audit and document dependency licenses to ensure compliance and identify GPL/AGPL restrictions that may affect commercial use.

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.