English | 中文
Accuracy-first, zero-barrier, lightweight CMDB for small and medium teams
Z-CMDB Lite is designed for IT operations and security engineers in small-to-medium teams (5–50 people). It manages intranet / office network / IDC / cloud assets via nmap scan uploads, for:
- Daily operations asset ledger
- Security audit & compliance readiness
- HVV / Red-Blue exercise asset inventory
- Port exposure analysis
Core design principles: SQLite single-file, zero middleware dependency, all write operations are auditable, sensitive data stays on-premises.
Z-CMDB supports three deployment methods: Windows double-click launcher (zero-install, embedded Python), Linux bare-metal (venv + systemd), and Docker (layered images, bind-mounted database). All methods use single-port FastAPI hosting with auto-generated JWT secrets.
| Method | Best For | Docs |
|---|---|---|
| 🪟 Windows Launcher | End users, air-gapped machines | deploy/DEPLOY_EN.md §1 |
| 🐧 Linux Bare-Metal | Small servers, VMs | deploy/DEPLOY_EN.md §2 |
| 🐳 Docker | CI/CD, containerized environments | deploy/DEPLOY_EN.md §3 |
Full deployment guide: deploy/DEPLOY_EN.md (English) | deploy/DEPLOY.md (中文)
Alongside security hardening, V0.7 adds unique hardware identity and a datacenter rack view:
- Unique hardware identity: serial number (SN), vendor, model, asset tag / barcode
- Structured rack location: datacenter / rack / start U / U height (the free-text location is kept as a display fallback)
- Multi-NIC / multi-IP: a dedicated interface inventory with name, MAC, multiple IPs, mask, VLAN, gateway, bond topology and a primary flag
- Out-of-band management: IPMI / iDRAC / iLO address
- Cloud & virtualization identity: cloud instance ID, region / availability zone, instance type; the hypervisor a VM belongs to
- Asset types extended: new storage, security device and load balancer types
- Rack layout (sidebar "Topology" group → "Rack Layout"): datacenter → rack → bottom-up 42U rack elevation, devices placed precisely by U position; click a device to see its ports and the same-datacenter upstream device (switch / storage / security / load balancer) and port, with warnings for out-of-range, overlapping and unlocated devices
Database migration (important): this release adds two migrations —
h5c0d4e6f2a9(hardware fields + interface table) andi6d1e5f7a3b0(rack entities + port-level cabling). Back upcmdb.dbandkeystore.jsonbefore upgrading.# Bare metal: from backend/ with the virtual environment active # Windows: .venv\Scripts\activate # Linux: source .venv/bin/activate cd backend && alembic upgrade headFor encrypted databases (V0.6.5+), simply restart and unlock in the browser — migrations run automatically as part of the unlock flow; existing assets'
(datacenter, rack)pairs are de-duplicated and backfilled as rack entities. Docker users take no manual action — migrations run automatically once the container starts and is unlocked.For the security hardening content (2 high, 5 medium fixes), see the V0.7 Security Hardening section.
V0.6.5 introduces static encryption. Existing plaintext databases must be migrated before starting the new version:
# 1. Stop the service # 2. Back up cp data/cmdb.db data/cmdb.db.bak # 3. Encrypt the database cd backend PYTHONPATH=. python tools/encrypt_existing_db.py \ --password '<your-admin-password>' # 4. Save the recovery code (one-time!) # 5. Restart → unlock via browserDo NOT skip this step. Starting V0.6.5 without migrating will result in a LOCKED state with no existing data accessible. See the V0.6.5 section for full details.
After pulling V0.5.1, run database migrations before starting:
# If using a virtual environment, activate it first: # Windows: cd backend && .venv\Scripts\activate # Linux/Mac: cd backend && source .venv/bin/activate cd backend && alembic upgrade headDocker users: no action needed — migrations run automatically on container startup.
This applies two new migrations:
e9f0a1b2c3d4— addstoken_versioncolumn touserstable (for token revocation on password change / account disable)f0a1b2c3d4e5— adds index onscan_snapshot_items.ip_address(performance optimization)Without running this command, the application will fail to start.
V0.6.5 adds at-rest encryption to Z-CMDB's SQLite database. A stolen .db file can no longer be opened by any SQLite tool — it appears as random bytes and requires an admin passphrase or recovery code, entered through the application, to unlock.
| Layer | Role |
|---|---|
| DEK (Data Encryption Key) | 32-byte random key, the actual SQLCipher/MC key. Never persisted in plaintext; held in memory only after unlock |
| KEK (Key Encryption Key) | Derived from admin passphrase via Argon2id (per-user salt). Used to wrap/unwrap the DEK |
| keystore.json | Stores wrapped DEK + salt + nonce (all ciphertext). Safe to back up; harmless if leaked without the passphrase |
- KDF: Argon2id (
memory=64MB, time=3, parallelism=4) - Wrap: AES-256-GCM (12-byte random nonce per wrap)
The application starts in LOCKED state (DB engine not initialized). After setup or unlock, it transitions to UNLOCKED with the DEK in memory.
| Action | Effect |
|---|---|
| Setup (first run) | Generate DEK → create admin → generate one-time recovery code → encrypt DB → unlock |
| Unlock (passphrase) | Derive KEK → unwrap DEK → init engine → run migrations → issue JWT (single-passphrase UX) |
| Unlock (recovery code) | Same as above, but does not auto-login (requires separate admin login after) |
| Change password | Re-wrap DEK with new KEK; database untouched |
| Add admin | Wrap DEK with new admin's KEK → add keystore record |
| Remove admin | Remove keystore record → passphrase immediately invalidated |
- Startup scripts no longer run
alembic upgrade head. Migrations run automatically after vault unlock/setup (encrypted DB cannot be migrated without the DEK). - Windows/Linux/Docker all support encryption. Unattended mode via
CMDB_UNLOCK_PASSWORDenvironment variable (injected at runtime, never written to.env). - One-time migration tool for existing plaintext databases:
python tools/encrypt_existing_db.py --password '<admin-password>'
- Recovery code: Generated once during setup, shown only once. It is the only way to recover if all admin passwords are lost. Store it offline immediately (paper, password manager).
- Backup: Always back up both
cmdb.dbandkeystore.json. Losing the keystore without a recovery code means permanent data loss. - Defended: Stolen
.dbfile / stolen.db+keystore.json(no passphrase) / full disk image (app not running). - Not defended: Process memory dump while running / compromised host with keylogger (see PRD §1 non-goals).
# 1. Stop the service
# 2. Back up
cp data/cmdb.db data/cmdb.db.bak
# 3. Run one-time encryption migration
cd backend
PYTHONPATH=. python tools/encrypt_existing_db.py \
--password '<new-admin-password>'
# 4. Save the recovery code printed to console (one-time!)
# 5. Restart → unlock via browserThe migration encrypts all tables (including views/indexes), verifies row counts, updates the admin password hash, and securely overwrites the plaintext original.
V0.7 is a security release. Following a full security audit of the V0.6.5 codebase, it fixes 2 high-severity and 5 medium-severity vulnerabilities, without changing any business workflow or API contract. Backend verification: 46 automated tests, all passing.
| Severity | Vulnerability | Fix |
|---|---|---|
| High | GET /api/hosts/search was reachable unauthenticated — exposing the asset ledger and allowing anonymous HostResource auto-creation |
Enforced authentication on the route; escaped LIKE wildcard characters (%/_) so they match literally |
| High | Auto-generated initial super-admin password was written in cleartext to data/INITIAL_ADMIN_PASSWORD.txt and stdout, so a data-directory backup could decrypt the encrypted database |
The generated password is delivered only once via the setup HTTPS response; CLI/script reset flows print it to the invoking terminal only — no file is ever created |
| Medium | Fernet field master key was derived from JWT_SECRET — no key separation, and rotating JWT_SECRET silently invalidated stored ciphertext |
Independent LLM_MASTER_KEY / 0600 data/llm_master.key; ciphertext is version-tagged; existing ciphertext is automatically re-encrypted on first unlock |
| Medium | Unvalidated llm_base_url enabled SSRF and stored-credential exfiltration |
URL validation both when the config is written and immediately before dispatch; loopback/private/link-local addresses are blocked by default; approved internal hosts are allowed via LLM_ALLOW_PRIVATE_BASE_URL |
| Medium | The upload size cap was enforced only after the full multipart body had been buffered into shared worker memory (OOM risk) | Added an ASGI body-size-limit middleware (Content-Length pre-check plus cumulative counting for chunked requests); endpoints now read uploads in bounded chunks |
| Medium | The auditor role could create, update and delete consuming units, placements and unit relations | All six write routes now require AdminUser; the project UI is fully read-only for auditors |
| Medium | Uploaded raw nmap/Excel files and JSON sidecars were stored indefinitely in cleartext outside the encrypted database | Raw files are no longer persisted; Excel extra fields are stored in the database (new migration); historical files are purged via scripts/cleanup_uploads.py |
- Field-encryption key separation: a 0600 key file
data/llm_master.keyis generated automatically during setup. When an existing system is upgraded, the file is generated lazily on first unlock and all legacy (JWT-derived-key) ciphertext is re-encrypted automatically — no manual action. In production the service fails closed if no independent key (environment variable or key file) is available. - SSRF protection: the built-in local Ollama auto-route (core assets) is an internal trusted path and remains fully functional; public cloud LLM endpoints work unchanged. To use an approved RFC1918 internal LLM host, set
LLM_ALLOW_PRIVATE_BASE_URL=truein the deployment environment (loopback addresses stay blocked). - Alembic migration:
g4b9c3d2e1f8adds a nullableextra_fields_jsoncolumn toscan_batchesand runs automatically after unlock. - Backups must now include
data/llm_master.keyalongsidecmdb.dbandkeystore.json.
# 1. Back up the data directory (cmdb.db + keystore.json)
# 2. Pull V0.7, restart, and unlock in the browser —
# key-file generation, ciphertext re-encryption and the alembic migration run automatically
# 3. After verifying, purge historical plaintext upload files:
python scripts/cleanup_uploads.py # preview
python scripts/cleanup_uploads.py --yes # delete
# 4. If an approved internal (RFC1918) LLM host is used:
# set LLM_ALLOW_PRIVATE_BASE_URL=true in the deployment environment, then restartV0.6 introduces a project perspective alongside the existing asset view, upgrading Z-CMDB from "record resources" to "let configuration data be continuously consumed by operations scenarios." It adds deterministic cost apportionment, interactive topology visualization, and project-aware dashboards.
- Project list: create, search, filter by business unit / owner / department, billing mode toggle per project, delete with name confirmation
- Project architecture page: interactive Vue Flow topology graph with deterministic template layout
- Hosts arranged left-to-right by dependency topology order; units stacked vertically within each host group
- Dependency edges (HTTP / SQL / cache / mq) with smoothstep arrows and type labels
- Shared hosts highlighted in orange with per-project allocation percentages
- Component cards with colored left bars by type (K8S / Docker / VM / Process)
- "Manage Dependencies" dialog in the component table for declaring unit-to-unit relations
- Project billing tab: frozen bill snapshots per period, 7-column cost breakdown table, shared host allocation explanation with full arithmetic formulas and conservation checks
- Full CRUD: create, edit, delete departments (super_admin only)
- Project association: projects can be linked to a department via dropdown selection (data sourced from the department registry)
- Department filter: project list supports filtering by department
- Reuses the existing
departmentstable from V0.4 cost accounting module
- Aggregates project billing costs grouped by department
- KPI cards: total cost, department count, total projects
- Pie chart showing cost distribution by department
- Summary table: department / project count / billing-enabled count / total cost
- Template download: standard .xlsx template with 19 columns (IP, MAC, hostname, OS, asset type, network zone, location, owner, business system, importance, CPU, memory, disk, purchase date, warranty expiry, port, protocol, service name, remark), headers include field descriptions
- Upload & parse: Excel files are parsed into the same
ParsedHoststructure as nmap scans, reusing the entire scan batch pipeline (diff computation → confirmation page → asset creation) - Row/column-level validation: errors are collected with precise row number and column name (IP format, enum values, port range, numeric fields)
- Confirmation page reuse: Excel imports go through the same scan batch confirmation page, with data source marked as "Excel Import"; supplementary fields (CPU, memory, disk, etc.) are pre-populated from the Excel data
- IP-based dedup: existing assets matched by IP are flagged as duplicates; new assets are created with
source="excel" - Remark preservation: all three remark mapping scenarios (structured → corresponding field, free text → remark field, multi-line → merged text) are supported
- Pure function: host monthly cost × memory share = allocated amount per unit
- Supports
allocatableorsum_requestsdenominator,mem/cpu/weighted/maxweight modes - Conservation assertion (tolerance 1e-6) — shares on every host sum to exactly 1.0
- Idle / unallocated costs go to a separate bucket (not forced onto projects)
- 6 new tables:
project,consuming_unit,placement,unit_relation,billing_policy,bill_snapshot host_resourceextended withip_addresscolumnprojectextended withdepartmentcolumnscan_batchesextended withsourcecolumn (scan/excel)assets.sourceCHECK constraint extended to includeexcel- Bill snapshots are frozen after generation — changing the billing policy does not alter historical periods
- KPI row expanded with 5 project-dimension cards: Projects, Consuming Units, Attribution Coverage, Monthly Project Cost, Global Unallocated Bucket
- Asset distribution donut chart gains a 5th tab: "By Project"
- Project summary module aggregated from
bill_snapshotdata, served through the existing dashboard cache
- AI project summary: removed the LLM-generated summary panel from the architecture page, the
/api/projects/{id}/summaryendpoints, andengine/summary.py. Topology is now fully deterministic.
- New Alembic migrations:
a2b3c4d5e6f7(v0.6 project tables),b7c8d9e0f1a2(summary cache columns — later removed),c8d9e0f1a2b3(host ip_address),d1e2f3a4b5c6(remove summary columns),e2f3a4b5c6d7(project department),f1a2b3c4d5e6(excel source support) - Version bumped to V0.6.0
V0.5.1 is a security-focused patch that addresses findings from a full codebase audit. No new features; all changes improve security posture, robustness, and data integrity.
- Initial admin password file auto-cleanup:
INITIAL_ADMIN_PASSWORD.txtis now automatically deleted after the admin changes their password; a startup warning is logged if the file still exists - Production JWT secret guard: the app now refuses to start with the default
JWT_SECRETwhenAPP_ENV=production - Bulk update enum validation:
PATCH /api/assets/bulknow validatesstatus,importance, andnetwork_zonevalues against allowed enums - Upload filename sanitization: nmap XML upload filenames are stripped of HTML/control characters to prevent stored XSS
- Removed deprecated
X-XSS-Protectionheader - ClaudeProvider retry logic: Claude API calls now retry 3 times with exponential backoff (matching OpenAIProvider behavior)
- Frontend error messages i18n: hardcoded Chinese error strings replaced with vue-i18n translation keys
decrypt_valueerror handling: decryption failures now log a warning and return empty string instead of silently returning raw ciphertext- Config API masking: non-super_admin users now see
****for all API key fields (super_admin retains partial masking) - CORS startup warning: logs a warning if
CORS_ORIGINScontains*or HTTP origins in production
token_versionmechanism: added to theuserstable — when a user changes their password or is disabled, all existing JWT tokens are immediately invalidated- Backward compatible: tokens issued before this update (without
tvclaim) continue to work until the user changes their password
- IP address index on
scan_snapshot_itemstable for faster scan history queries - LLM log prompt truncation reduced from 500 to 200 characters
- Asset list default sort: changed from IP address to asset number (
asset_no) - 403 error display: now shows the actual backend error message (e.g., "Feature not enabled") instead of a generic "Permission denied"
- Cost feature toggle: added error handling — if the toggle API fails, the user now sees an error message instead of a silent failure
- New Alembic migration:
e9f0a1b2c3d4(token_version),f0a1b2c3d4e5(ip index) - Version bumped to V0.5.1
V0.5 adds an Import Preset system to eliminate repetitive data entry during scan import, manual asset creation, and batch editing. It also improves the scan workflow with upload progress indicators and batch processing feedback.
- New settings page under "Scan Import" in the sidebar — two-column layout (category list + preset table)
- Three preset categories: Physical Location, Owner, Business System
- Full CRUD: add, edit, delete, search, sort order, remarks
- One default value per category (DB-enforced via partial unique index)
- Sync from Assets: one-click extract distinct values from existing assets into the preset library
- Presets are team-global, not per-user; deleting a preset does not affect existing asset values
- Reusable dropdown (
PresetSelect) shared across three scenes: scan confirm, manual create, batch edit - Filterable
el-selectwith clearable selection - Inline add: footer slot with input field — add a new preset value directly from any dropdown without leaving the page
- Default value auto-fill when creating new assets or importing scans
- Location / Owner / Business System fields replaced with
PresetSelect(was plain text input) - Batch Preset Toolbar: field selector + value selector + scope (selected rows / all rows) + apply button — batch-set values across hundreds of rows in one click
- Step loading indicator: shows "Loading presets..." → "Computing diff..." with animated dots instead of blank spinner
- Import overlay: full-screen overlay with spinner during confirm submission, prevents double-click
- Manual create/edit: Location, Owner, Business System fields now use
PresetSelectwith default pre-fill - Batch edit: asset list gets checkbox multi-select + batch edit dialog — select assets, choose field (owner / business system / location), pick preset value, apply
- XML upload now shows a real progress bar with percentage (XHR
upload.onprogress) - After file transfer completes, switches to indeterminate pulse animation ("Processing scan data...")
- Axios timeout for scan APIs increased from 30s to 120s
- Global scrollbar style updated to 10px solid (was 4px visible with transparent border trick)
- New database table:
import_preset(category, value, is_default, sort_order, remark) - New Alembic migration:
c7d8e9f0a1b2 - New API endpoints: 7 endpoints under
/api/import-presets PATCH /api/assets/bulknow supportslocationfield- Full i18n: all new UI strings bilingual (English + Chinese)
- Version bumped to V0.5.0
V0.4 adds an opt-in Asset Cost Accounting module to Z-CMDB Lite, covering hardware depreciation, department billing, and cost governance. The feature is off by default — when disabled, the system behaves exactly as V0.3.
- 6 KPI cards (Monthly Total, Annualized, CapEx/OpEx Ratio, New Cost Assets, Missing Data)
- 4 charts: Department Ranking, Asset Type Distribution, Cloud vs On-Prem, Cost Trend
- Cost Governance list (Shadow Cost / Low Utilization / Depreciation Expiring / Missing Data)
- Period selector with recent 12 months, CSV export
| KPI Strip & Charts |
|---|
- Two-column layout: searchable department list + billing content
- Period summary (Day/Month/Year/Custom) with 3 KPIs
- Resource detail table + Cost Type donut + Resource Ranking bar chart
- CSV export with full billing detail
| Summary |
|---|
- 3 KPI cards: Full-Loaded Monthly Cost, Net Value, Remaining Depreciation Months
- Cost distribution donut + detail list with progress bars
- Depreciation info section with progress bar
- Expiry warning banner with strategy selection
- Depreciation table (6 asset types × years/residual/method/strategy)
- Power, bandwidth, datacenter parameters
- Resource Price Book with enable toggles
- Allocation drivers per asset type
- Currency selector (CNY/USD) — all displays switch automatically
- Hero-style toggle card to enable/disable the entire cost module
- Super_admin only, confirmation dialog when disabling
- Quick-access links when enabled
- Asset list sorting: all 10 columns support click-to-sort
- Timezone-aware display: timestamps switch between Asia/Shanghai and America/New_York by UI language
- Currency-aware display: amounts switch between ¥/CNY and $/USD by cost rate settings
- GoatCounter analytics: privacy-friendly page visit tracking
- Version bumped to V0.4.0
V0.3 brings full internationalization (i18n) to Z-CMDB Lite, adding English/Chinese bilingual support across the entire frontend. The default language is now English, with one-click switching available from any page via the topbar toggle or System Config. The README documentation is also split into separate English and Chinese editions.
- Complete English translation of all 16 pages and 3 shared components — every button, label, tooltip, validation message, and chart title is localized
- Topbar language toggle (EN/中) for instant switching from any page without navigating to settings
| English | Chinese |
|---|---|
- System Config language selector (section 00) with dropdown for English / Chinese
- Persistent preference saved to
localStorage— language choice survives browser refresh and restarts - Element Plus locale sync — pagination text, date pickers, table empty states, and all built-in component labels switch dynamically via
ElConfigProvider - ECharts chart re-rendering — dashboard charts (topology, distribution, port exposure) automatically re-render with localized labels on language switch
README.md(English, default) andREADME_zh.md(Chinese) with mutual language toggle links at the top of each file- Both editions stay in sync with identical structure and screenshots
V0.2 introduces the Asset Overview (/dashboard) as the default homepage after login, aggregating key metrics previously scattered across reports and asset lists into a single view, enabling operations and security engineers to grasp the overall asset security posture at a glance. This release also includes a round of frontend engineering quality improvements.
All page data is provided by the backend aggregation endpoint GET /api/reports/dashboard-summary in a single request (SQL aggregation + 30s TTL cache, full page refresh triggers only one request). The page consists of 5 modules:
KPI Cards (8 metrics) Total Assets · Online · Offline · Decommissioned · Dangerous Ports · Shadow Assets · Monthly Changes · Scan Coverage. Numbers animate with a flip effect on page entry; "Online / Offline / Decommissioned" cards are clickable, linking directly to the asset list with pre-applied status filters.
Network Zone Topology
ECharts force-directed layout, aggregated by network_zone, node size reflects asset count; zones with core assets are highlighted with red borders, supports drag and zoom exploration.
Asset Distribution Donut Chart Center displays total asset count, top tabs switch between four dimensions: Network Zone / Asset Type / Importance / OS.
Port Exposure Left side: Top 10 open ports horizontal bar chart (dangerous ports auto-highlighted in red); right side: donut chart showing distribution by network zone.
Dangerous Port Alert Scrolling List Scrolling broadcast of dangerous port details (IP / Port / Service / Zone / Level), color-coded by severity (high-risk with pulse animation), auto-pauses on mouse hover for inspection.
- Removed deprecated large-screen code: Cleaned up the unused fixed-resolution large-screen implementation (
panels/*,ScreenContainer,registry), unified as the responsive Asset Overview page as the sole implementation, eliminating dual code paths and inconsistent color schemes - Performance: Backend cache hit on first load (only "Refresh Data" button forces refresh), window
resizedebounce, ECharts instances useshallowRef, removed redundantdeepwatchers - Responsive: Added desktop / laptop / tablet breakpoints, KPI cards adapt from 8 → 4 → 2 columns, dual-column cards auto-stack to single column on narrow screens
- UX: Loading skeleton screens replace blank pages, clickable KPIs add hover feedback, dangerous port list auto-pauses scrolling when page is backgrounded (fixes background idle and timer leaks)
- Accessibility: Number flip, high-risk pulse, and auto-scroll respect system "Reduce Motion" (
prefers-reduced-motion) settings - Maintainability: Zone colors / dangerous ports / zone mapping constants extracted as single source (
constants/dashboard.ts), KPI icons extracted as independent components
Full changelog at the end of this document: Changelog.
- Supports 8 asset types: Physical Server, Virtual Machine, Cloud Server, Network Device, Storage, Security Device, Load Balancer, Other
- Records unique hardware identity: serial number (SN), vendor, model, asset tag, plus the out-of-band (IPMI/iDRAC/iLO) address
- When Cloud Server is selected, network zone auto-switches to cloud provider (Alibaba Cloud / Tencent Cloud / Huawei Cloud / AWS / Azure / GCP)
- Multi-dimension filtering: Network Zone, Asset Type, Importance, Status
- Full-text search: IP, Hostname, Asset Number, Business System, Application Name (e.g., nginx, mysql)
- Batch operations: Batch modify Owner, Business System, Importance, Network Zone
- Export: Standard CSV + Threat Hunting Assistant compatible format
Multiple tabs for one-stop viewing:
| Tab | Content |
|---|---|
| Basic Info | Asset Number, IP/MAC/Hostname, OS, hardware identity & ownership, hardware specs, procurement & warranty |
| Ports | Open ports discovered by scan, including service name, version, status |
| Network Interfaces | Multi-NIC/multi-IP, VLAN, bond; register same-datacenter upstream device and switch port |
| Applications | Manually registered or scan-extracted application list, including version, port, install path |
Port-Application bidirectional sync: When manually adding an application with ports, it auto-writes to the ports table; when confirming nmap scan import, ports with service_name automatically generate application records.
- Run nmap on a jump host to generate an XML report
- Upload to the platform, auto-parse and perform diff analysis against existing assets
- Diffs are categorized into four types: New Discovery / Change / Disappearance / Recovery
- Manually review each host's port change details before confirming import
- Disappeared hosts are not immediately deleted;
missing_count + 1, marked offline only after exceeding the threshold
- One-click LLM invocation to generate a draft drawio network topology diagram
- Supports DeepSeek / OpenRouter / Local Ollama
- Asset data is auto-anonymized before being s 10BC8 ent to the LLM (IP → placeholder, business system → code name)
- Core assets can be configured to force local model usage; sensitive data stays on-premises
- After generation, manual adjustments can be made in the embedded drawio editor, with version management and rollback support
- Aggregates racks by datacenter so managers instantly see which datacenters exist, how many racks each has, and U utilization
- Racks are drawn as a 42U elevation (U1 at the bottom, bottom-up); servers are placed precisely by their registered U position and color-coded by device type
- Clicking a device shows its ports and the same-datacenter upstream device (switch / storage / security / load balancer) and port in the side panel, while connected devices are highlighted
- Data-quality warnings: out-of-range U, overlapping U and unlocated devices, with quick data-entry support
- Asset distribution: Network Zone, Importance, OS, Asset Type
- Port exposure analysis: Top ports, dangerous port statistics
- Scan coverage: Recent scan time distribution
- Threat Hunting Assistant compatible export: Expanded by "Asset x Application", including environment / criticality / exposure_scope / vendor fields
- Records all login, CRUD, export, and LLM call operations
- Tamper-proof: SQLite triggers at the database layer prevent UPDATE / DELETE
- Supports filtering by action type, user, target type
Three roles with separation of duties:
| Role | Permissions |
|---|---|
super_admin |
All operations + User management + System configuration |
admin |
Asset CRUD, Scan upload & confirm, Topology generation |
auditor |
Read-only + Audit log viewing |
The system requires at least one auditor account to be created before unlocking full functionality (compliance separation-of-duties requirement).
- LLM Provider / API Key / Model / Base URL
- Core asset routing policy (whether to force local Ollama)
- Asset number prefix (default
CMDB) - Scan disappearance threshold (consecutive N scans without detection before marking offline)
- Upload file size limit
| Layer | Choice |
|---|---|
| Backend Language | Python 3.11+ |
| Web Framework | FastAPI |
| Database | SQLite 3 (WAL mode, single file) |
| ORM | SQLAlchemy 2.0 |
| Data Migration | Alembic |
| Frontend Framework | Vue 3 + Vite + TypeScript |
| UI Component Library | Element Plus |
| State Management | Pinia |
| Password Hashing | argon2id |
| Authentication | JWT (access + refresh token) |
| Deployment | Docker + docker-compose |
# 1. Clone the project
git clone https://github.com/Zer00n/z-cmdb.git
cd z-cmdb
# 2. Configure JWT secret
cp secrets/jwt_secret.txt.example secrets/jwt_secret.txt
# Edit secrets/jwt_secret.txt, enter a random string (recommended 32+ characters)
# 3. Start
docker compose -f docker/docker-compose.yml up --build -d
# 4. Access
# http://localhost:8080
# 5. Complete first-time Vault Setup in the browser
# Set admin username + password (leave the password field blank to have one
# generated and shown once on the result page), then log in
# Default account: admin (no password file is created)
# (Optional) Preset initial password, consistent for both Docker and Windows modes:
# Create a .env file in the repository root, write:
# CMDB_INITIAL_ADMIN_PASSWORD=YourPassword@123
# Then start with:
# docker compose --env-file .env -f docker/docker-compose.yml up --build -dOne-click Start
The project root provides Windows batch scripts, double-click to start both frontend and backend simultaneously:
dev-start.bat # One-click start backend + frontend (auto-opens two terminal windows)
dev-stop.bat # One-click stop all services
Prerequisite: Complete the environment initialization below (venv + pnpm install + alembic upgrade head).
Environment Initialization (First time only)
# Backend
cd backend
uv venv
.venv\Scripts\activate
uv pip install -r requirements.txt
alembic upgrade head
# Frontend
cd ..\frontend
pnpm installManual Start (for separate debugging)
Backend:
cd backend
.venv\Scripts\activate
uvicorn app.main:app --reload --host 127.0.0.1 --port 8000Frontend (new terminal):
cd frontend
pnpm devAccess http://localhost:5173 Complete Vault Setup on first visit (the initial password is shown once on the setup result page, never written to a file).
z-cmdb/
├── backend/
│ ├── app/
│ │ ├── cli.py # Management CLI (init-db / reset-admin)
│ │ ├── core/ # Config, security, dependency injection, encryption
│ │ ├── models/ # SQLAlchemy models
│ │ ├── schemas/ # Pydantic v2 Schemas
│ │ ├── routers/ # API routes
│ │ ├── services/ # Business logic
│ │ ├── repositories/ # Data access layer
│ │ └── utils/ # nmap parsing and other utilities
│ ├── alembic/ # Database migration scripts
│ └── requirements.txt
├── frontend/
│ └── src/
│ ├── views/ # Page components
│ ├── components/ # Shared components
│ ├── api/ # API wrappers
│ ├── stores/ # Pinia state
│ ├── styles/ # Global styles & Design Tokens
│ ├── types/ # TypeScript type definitions
│ └── constants/ # Enum constants (OS options, app categories, etc.)
├── docker/ # Dockerfile & docker-compose
├── scripts/ # Operations scripts (password reset, audit export, etc.)
├── secrets/ # JWT secret (not committed, only .example files)
├── img/ # Feature screenshots
└── README.md
# Quick scan (common ports)
nmap -sV -T4 -oX scan_result.xml 192.168.1.0/24
# Full port scan
nmap -sV -p- -T4 -oX scan_full.xml 192.168.1.0/24
# Specific ports + OS detection
nmap -sV -O -p 22,80,443,3306,6379,8080 -oX scan_web.xml 192.168.1.0/24After scanning, upload the .xml file to the "Scan Batches" page on the platform.
- Passwords use argon2id hashing (memory=64MB, time=3, parallelism=4)
- JWT supports access token (short-lived) + refresh token (long-lived)
- Account auto-locks after exceeding failed login threshold
- All response headers include CSP / X-Content-Type-Options / X-Frame-Options
- Audit logs are tamper-proof via database triggers
- Asset data is anonymized before LLM calls; core assets can be forced to use local models
Docker environment:
# Reset to random password (new password printed to the terminal only, never written to a file)
docker compose -f docker/docker-compose.yml exec backend python -m app.cli reset-admin
# Reset to a specific password
docker compose -f docker/docker-compose.yml exec backend python -m app.cli reset-admin --password 'YourNew@Pass1'Local development:
cd backend
.venv\Scripts\activate
python -m app.cli reset-admin
# Or specify a password:
python -m app.cli reset-admin --password 'YourNew@Pass1'This project is not recommended for production deployment.
Z-CMDB Lite is designed as a local tool for individuals or small teams, suitable for the following usage patterns:
- Deployed on a local machine or intranet workstation, started on demand
- Shut down after use (
dev-stop.bator close terminal); do not leave it exposed on the network long-term - Do not expose the service port to the public internet; if remote access is needed, use VPN or SSH tunnel
- Database is a single SQLite file (
backend/data/cmdb.db); back up regularly - Change the default admin password immediately after first login (system will enforce this)
If your use case involves concurrent writes from multiple users (>50 people), high availability, or public-facing services, please consider production-grade database solutions like PostgreSQL.
Upgrade note: After pulling V0.6, run
alembic upgrade headin thebackend/directory. This applies 6 migrations: project tables, host ip_address, summary columns (added then removed), project department, and Excel source support.
Project Management
- New
/projectsroute with project list, per-project architecture page (Vue Flow topology), and billing tab - 6 new database tables:
project,consuming_unit,placement,unit_relation,billing_policy,bill_snapshot host_resourceextended withip_address- Project delete: delete button with name-confirmation dialog (type exact project name to confirm)
- Department field:
projecttable extended withdepartmentcolumn; project list supports department filter; project create/edit uses department dropdown
Department Management (/departments)
- New admin page for full CRUD of departments (create / edit / delete)
- Reuses existing
departmentstable from V0.4 cost module - Sidebar entry under "System Admin" group
Project Cost Summary (/projects/billing/departments)
- New page aggregating project billing costs grouped by department
- KPI cards (total cost, department count, total projects) + pie chart + summary table
- API endpoint:
GET /api/projects/billing/department-summary?period=YYYY-MM
Excel Asset Import
- Template download:
GET /api/scans/template/excel— standard .xlsx with 19 columns, headers include field descriptions - Upload endpoint:
POST /api/scans/upload-excel— parses Excel intoParsedHost, reuses entire scan batch pipeline - Row/column-level validation with precise error location (row number + column name)
- Confirmation page reuses scan batch confirmation; supplementary fields (CPU, memory, disk, etc.) pre-populated from Excel
- IP-based dedup: existing assets flagged as duplicates, new assets created with
source="excel" scan_batchestable extended withsourcecolumn (scan/excel)assets.sourceCHECK constraint extended to include'excel'- New dependency:
openpyxl>=3.1.0
Topology (Vue Flow)
- Replaced HTML/CSS topology with Vue Flow interactive canvas
- Deterministic template layout: hosts sorted by dependency topology order, units stacked vertically per host
- Custom node components:
HostGroupNode(shared host orange highlight),UnitNode(type-colored left bar) - Dependency edges: smoothstep arrows with rel_type labels, cycle detection (dashed orange)
- "Manage Dependencies" dialog in component table (create / delete
unit_relation)
Billing
- On-read freeze pattern: bill generated from apportion engine on first read, then frozen
- Enriched bill response: unit/host names, host monthly cost, memory ratio (absolute + percentage), host details, previous period comparison
- 7-column cost breakdown table, shared host allocation explanation module with conservation checks
- Root cause fix: populated
monthly_cost/cpu_total/mem_totalon allhost_resourcerecords
Dashboard
- 5 new project-dimension KPI cards (Projects, Consuming Units, Attribution Coverage, Monthly Project Cost, Global Unallocated)
- New
_build_project_summary()aggregation in dashboard service (reads frombill_snapshot, same TTL cache) - Asset distribution pie chart gains "By Project" tab (5th dimension)
- Unified KPI grid with separator, scrollable legend with text truncation
Removed
- AI project summary: deleted
engine/summary.py,/api/projects/{id}/summaryendpoints,Projectmodel summary cache columns, related i18n keys and PRD sections
Migrations
a2b3c4d5e6f7— v0.6 project tablesb7c8d9e0f1a2— summary cache columns (added then removed in same release)c8d9e0f1a2b3— host ip_addressd1e2f3a4b5c6— remove summary columnse2f3a4b5c6d7— project department columnf1a2b3c4d5e6— Excel source support (scan_batches.source + assets CHECK)
Upgrade note: After pulling V0.5, run
alembic upgrade headin thebackend/directory to create the newimport_presettable. Without this step the application will fail to start.
Import Presets
- New
/import-presetssettings page under "Scan Import" sidebar group, two-column layout (category list + preset table) - Three preset categories:
location,owner,business_system— full CRUD with search, sort order, remarks - One default value per category enforced by partial unique index (
ix_preset_one_default) - "Sync from Assets" button: extracts distinct non-empty values from existing assets, deduplicates against existing presets
- New database table
import_presetwith Alembic migrationc7d8e9f0a1b2 - 7 new API endpoints under
/api/import-presets(list, categories, create, update, set-default, delete, sync-from-assets) - All write operations logged to audit via
audit_service.log_from_request
PresetSelect Component
- Reusable
el-selectcomponent withfilterable+clearable+ footer slot for inline add - Shared across scan confirm, manual asset create, and batch edit
- Backed by Pinia store (
useImportPresetStore) with lazy-loading and per-category cache
Scan Confirm Page
- Location / Owner / Business System fields replaced with
PresetSelect(wasel-input) - Default values auto-filled from preset library on page load
- Batch Preset Toolbar: field + value + scope (selected/all) + apply — pure frontend operation
- Step loading indicator: "Loading presets..." → "Computing diff..." with animated dots
- Full-screen import overlay during confirm submission (prevents double-click)
Asset Form & Asset List
- Asset create/edit form: Location, Owner, Business System replaced with
PresetSelect, defaults pre-filled for new assets - Asset list: new checkbox selection column + batch edit dialog with
PresetSelect PATCH /api/assets/bulkextended to supportlocationfield
Scan Upload Progress
- Upload uses
XMLHttpRequest.upload.onprogressfor real percentage display (0–100%) - After file transfer, switches to indeterminate pulse animation during server-side processing
- Axios timeout for scan upload/diff/confirm APIs increased from 30s to 120s
Other
- Global scrollbar width increased to 10px solid (was 4px effective with transparent border)
- All new UI strings fully bilingual (English + Chinese) via vue-i18n
Asset Cost Accounting (opt-in)
- Added
feature_cost_accounting_enabledfeature flag in System Config (default OFF, super_admin only) - Cost Overview dashboard (
/cost/overview): 6 KPIs, 4 ECharts (dept ranking, type donut, cloud vs local, trend), governance list with tabs - Department Billing (
/cost/billing): searchable dept list, period selector (day/month/year), resource detail table, cost type donut + resource ranking bar, CSV export - Asset Detail → Cost Breakdown tab: 3 KPIs (full-loaded monthly, net value, remaining months), cost distribution donut, depreciation progress bar, expiry warning
- Cost Rate Settings (
/cost/rates): depreciation params per asset type, power/bandwidth/datacenter params, resource Price Book (vCPU/mem/storage/bandwidth/IP), allocation drivers, currency selector (CNY/USD) - Asset Form → Section 04 cost fields (purchase price, depreciation months, residual rate, method, strategy, billing mode, responsible department)
- 5 new database tables: departments, asset_cost_items, asset_relations, asset_dept_assignments, cost_rates
- Asset table extended with 10 cost fields (purchase_price, depreciation_months, residual_rate, etc.)
- Pure computation engine: straight-line depreciation, revalue strategy, shared cost allocation (by driver/even split), conservation check
- All cost APIs guarded by centralized
require_cost_featuredependency; feature off → 403
Asset List Sorting
- All 10 columns (asset_no, IP, hostname, type, zone, business system, OS, importance, status, owner) now support click-to-sort ascending/descending via Element Plus
sortable
Timezone & Currency
- All timestamps switch timezone by UI language: zh → Asia/Shanghai (UTC+8), en → America/New_York
- Cost amounts switch currency symbol by rate settings: CNY → ¥, USD → $
- New
useTimeFormatanduseCostCurrencycomposables centralize all display logic
i18n
- Added
cost.tslocale module (en + zh) with 200+ keys covering all cost pages, forms, charts, CSV exports - Fixed
[intlify] Not foundwarnings: array values usetm(), null-safe guards on all label functions - Fixed
el-paginationsmallprop deprecation →size="small"
Analytics
- Integrated GoatCounter page visit tracking (privacy-friendly, async)
allow_local: trueenables localhost/dev tracking- Fallback script injection in Login.vue in case index.html script is removed
Internationalization (i18n)
- Added full English/Chinese bilingual support via vue-i18n@9 (Composition API mode)
- Default language changed to English; all UI strings translated
- Language toggle button in topbar (EN/中) for quick switching from any page
- Language settings card in System Config page (section 00) with dropdown selector
- Language preference persisted to localStorage across sessions
- Element Plus component locale (pagination, date pickers, table empty text) dynamically switches via ElConfigProvider
- README split into English (
README.md, default) and Chinese (README_zh.md) with mutual language toggle links - Translation files organized by module: common, layout, router, login, dashboard, asset, scan, topology, report, audit, user, settings, help, components, constants
- Shared
useTranslatedLabels()composable centralizes zoneLabel/importanceLabel/statusLabel/typeLabel/roleLabel functions
Asset Overview
- Added
/dashboardAsset Overview page as the default homepage after login - 8 KPI metric cards (Total Assets, Online/Offline/Decommissioned, Dangerous Ports, Shadow Assets, Monthly Changes, Scan Coverage) with number flip animation
- Network Zone Topology (ECharts force-directed), aggregated by
network_zone, core assets highlighted with red borders - Asset Distribution donut chart, supporting Network Zone/Asset Type/Importance/OS dimension switching
- Port Exposure: Top 10 open ports horizontal bar chart + distribution by zone donut chart
- Dangerous Port Alert scrolling list, color-coded by severity (high-risk pulse animation), auto-pauses on hover
- Shadow Assets (missing fields + long-term offline) tab switching display
- Asset change timeline, audit & LLM activity stream scrolling broadcast
- Backend aggregation endpoint
GET /api/reports/dashboard-summary, SQL aggregation + 30s TTL cache, single refresh triggers only one request - Dangerous port list and high-risk zones migrated from hardcoded to
system_configsconfiguration, reports and overview share the same judgment logic - Layout persistence (personal layout + global default),
system_configsKV storage
Docker Deployment Fixes
- Backend dependencies switched to
/opt/venvvirtual environment, fixingimport sqlalchemyfailure indocker exec - Added in-app CLI
python -m app.cli(init-db/reset-admin), no need to copy scripts into the container - Initial password controllable: supports
CMDB_INITIAL_ADMIN_PASSWORDenvironment variable preset, random generation and write todata/INITIAL_ADMIN_PASSWORD.txtif not set - Added
COOKIE_SECUREconfiguration, fixing refresh token cookie rejection by browsers under HTTP deployment - Added
.env.exampleenvironment variable template - Local development scripts (
scripts/reset_admin.py,init_db.py) path logic corrected, reusing CLI service layer
Topology Improvements
- Fixed routing to Ollama reusing OpenRouter model name causing 502 error
- Added Ollama availability detection, showing clear Chinese prompt when unavailable (instead of cryptic 502)
- Added
llm_ollama_modelindependent configuration, Ollama routing uses dedicated model name - LLM provider simplified to "Custom" and "Local" two options, custom supports any OpenAI-compatible API
- Topology page added "Generation Log" tab, showing LLM call process and details (provider/model/latency)
- Fixed config page saving masked values overwriting real API Key bug
Other Improvements
- Fixed change password 422 error: frontend password policy validation (>= 12 chars + uppercase/lowercase/digit/symbol) aligned with backend
- 422 Pydantic validation error messages correctly displayed (extracting
msgfromdetailarray) - Backend
llm_service.get_provider()no longer validates provider name, non-ollama always uses OpenAI-compatible interface