GuiLiu

Open-source Security Data Access Layer. Unified security data, independent conclusions.

English · 简体中文

The project remains in 0.x development; 1.0 has not been released. See the current version, changelog and versioning policy.

GuiLiu collects alerts from cloud security services, normalizes them into a shared fact contract with source-appropriate OCSF projections, and preserves the original vendor payload. Security teams and their own agents query the same data through a web console, REST API, read-only MCP tools, or a read-only query CLI.

Built by BaiLi Labs. Self-hosted, with a single Go binary and an embedded web console.

Why GuiLiu

Working across clouds means maintaining separate credentials, queries, severity scales, and evidence formats. An agent needs those integrations just as much as an analyst does.

GuiLiu provides a common data layer:

• Reliable ingestion. Incremental windows, rate limits, retries, and page-level checkpoints. Failed mappings retain their raw payload separately and are retried without blocking newer alerts.
• Consistent queries. A shared fact contract for source severity/status, accounts, assets, IPs, hashes, users and evidence. OCSF classification follows source semantics; missing facts remain unknown.
• Original data. Vendor JSON and mapping versions remain available alongside normalized fields. Query-time grouping preserves the underlying alerts.
• Human and agent access. One dataset across the console, REST API, 20 read-only MCP tools, and a read-only query CLI for shell agents and automation. Bring your own agent.

A typical workflow: connect cloud accounts, filter or group alerts, inspect the original data, then let your existing agent query the same records through MCP or the query CLI. Analysis and response stay with the tools you choose.

See the data access contract for persistent change feeds, pinned query snapshots, field provenance, full revision pagination and machine-readable coverage. Development schema 5 requires a new database; existing databases are rejected without being erased.

The first asset adapters cover six clouds: Tencent CVM, Alibaba ECS, Huawei ECS, AWS EC2, GCP Compute and Azure VM. They provide instance metadata, OS, IPs, network-interface, VPC, subnet and security-group references, and tags, with scoped references to independent NICs, security groups, VPCs and subnets. Follow those references to query names, CIDRs, tags, source policy evidence and revisions. Reads use saved local observations; administrators can explicitly refresh an instance or one network resource. Source capabilities are kept apart: GCP does not treat firewalls as instance security groups, Huawei does not invent a subnet ID, and Azure follows only the NICs explicitly referenced by the VM. Tencent has completed the full investigation path against one real account and host on a schema-5 database: 72 hours of alerts, alert to host asset, NIC/network references, related alerts and exact evidence, with matching REST, MCP and query-CLI results (the Web reuses the same REST endpoints). Alibaba, Huawei, AWS, GCP and Azure still have synthetic-response and contract validation only and await per-account verification. Software, listening ports, and reachability observations are not collected. See the asset contract.

Web, REST and MCP access is recorded in a persistent audit with user/API key identity, query scope, result references and timing. Administrators can trace related calls in Access audit. Credentials and raw evidence bodies are excluded; retention defaults to 90 days. See the audit contract.

Connector coverage

Each connector targets a specific cloud security API. Other products are visible only when their alerts are included by that upstream service.

Microsoft Defender for Cloud (Azure Resource Manager) and Microsoft Defender XDR (Microsoft Graph) are separate connectors with separate permissions.

The console supports English and Simplified Chinese, remembers language and appearance preferences, and formats dates and numbers for the selected language. Vendor alert content remains in its original language.

Push ingestion

Records pushed by a product enter the same normalization, deduplication, retention and revision pipeline as polled records:

• POST /ingest/{account} with Authorization: Bearer <push_token>.
• Syslog RFC 5424 / RFC 3164 over TCP or UDP on intake.syslog_listen, with CEF header and extension decoding.

Creating a push-only source in the console generates a token, shown once. Administrators can generate or rotate it from the account list. Only its SHA-256 is stored; ordinary reads and audit records never return the token. Alternatively, set push_token in configuration. Configuration-managed tokens must be changed there and require a restart; console rotation cannot override them.

Push-only sources need no product credential and are skipped by the scheduled poller. The console distinguishes waiting, receiving, and no recent events; recent delivery does not prove complete delivery for a time range. TCP applies backpressure and shutdown attempts to drain queued frames within five seconds. UDP and process crashes can still lose frames that have not reached storage. Saved transport envelopes can be replayed after a mapping fix.

Push transports carry alerts, not general logs. The generic CEF connector requires an explicit event_categories list and ingests nothing without it, so traffic or audit records cannot be mistaken for findings. Syslog is disabled by default; when enabled it must stay on a trusted network, and without TLS the transport is unencrypted and unauthenticated.

Each CloudWalker account collects one event_type, defaulting to webshell_event. Create separate accounts with the same appliance and credential for the other seven families. Coverage responses expose the configured family and time format. Cosmos and CloudWalker mappings remain unverified pending real responses.

Try it locally

Requirements: Go 1.26+, Node.js 20+, and npm.

make mock

Open http://127.0.0.1:8081. The demo contains 56 synthetic alerts across six providers, uses an in-memory database, and disables authentication and scheduled ingestion. It does not require cloud credentials.

Download release bundles

The executable is gl-cli (gl-cli.exe on Windows). Tagged versions on GitHub Releases provide Linux, macOS and Windows bundles for amd64 and arm64. Each archive includes the executable, query Skill, both READMEs, LICENSE, NOTICE and public documentation. Check its SHA-256 against SHA256SUMS, extract the archive and run ./gl-cli version (.\gl-cli.exe version in PowerShell). To start the server, copy configs/guiliu.example.json to guiliu.json, configure the initial admin password as below, then run ./gl-cli serve.

Only deliberately pushed version tags build releases; changing the development version or pushing a branch does not publish one. See the release procedure and signing limits.

Deploy

Build the embedded console and server:

make build
cp configs/guiliu.example.json guiliu.json
export GUILIU_ADMIN_PASSWORD='replace-with-a-long-initial-password'
./bin/gl-cli serve

Open http://127.0.0.1:8080, sign in as admin, and connect an account from Cloud accounts. Use read-only cloud permissions.

For Docker:

docker build -t guiliu:dev .
docker run --rm -p 127.0.0.1:8080:8080 \
  -v "$PWD/data:/data" \
  -e GUILIU_ADMIN_PASSWORD='replace-with-a-long-initial-password' \
  guiliu:dev

The current storage implementation is single-instance SQLite. Preserve the database and encryption key together when backing up. For remote access, configure an HTTPS reverse proxy and secure cookies; see the deployment and operations guide.

Connect your agent

In API & MCP, create an API key and copy the HTTP configuration into your MCP client:

{
  "mcpServers": {
    "guiliu": {
      "type": "http",
      "url": "http://127.0.0.1:8080/mcp",
      "headers": {
        "Authorization": "Bearer <API_KEY>"
      }
    }
  }
}

For example, ask your agent to find high-severity alerts from the last 24 hours, group by type and asset, then expand the original alerts and cite their IDs. Groups match exact field values; counts are alert records, and maximum severity comes from the vendor-mapped member levels. Grouping makes no false-positive judgments. Check ingestion progress before interpreting an empty result.

MCP tools are read-only, with limits of 200 records per call and a 90-day query window. Alert lists default to the last seven days and include account ingestion status. API keys inherit their owner's role and access all cloud accounts in the instance. REST endpoint details and stdio setup are in the API and MCP guide.

CLI and skill

The same binary includes a read-only query client over the REST API for shell agents, CI, batch exports and pagination. It does not need an MCP client and does not read the database directly:

export GUILIU_URL="http://127.0.0.1:8080"
export GUILIU_API_KEY="glk_..."

gl-cli query describe
gl-cli query alerts --since 24h --severity high,critical --limit 20 --json
gl-cli query alerts --since 7d --all --max-items 500 --ndjson | jq -c '{id,severity,title}'
gl-cli query changes --cursor 12345 --limit 100 --json
gl-cli query coverage --since 7d --json

Output is a human table by default, --json is the exact REST body for one page, and --ndjson emits one record per line for --all batches. Metadata and coverage warnings go to stderr. gl-cli query describe is the compact command catalog; use <command> --describe for flags/field names and add --schema for full response structures. The companion agent skill lives in skills/guiliu-query/SKILL.md. CLI calls carry X-Guiliu-Client: cli, so the access audit records surface=cli.

Security and deployment boundaries

• Local users with admin and viewer roles; authenticated access is required by default.
• Argon2id password hashes, HttpOnly session cookies, and revocable API keys stored as hashes.
• Cloud credentials encrypted at rest with AES-256-GCM.
• Platform alert status is independent of vendor status. GuiLiu does not write changes back to cloud services.
• A shared dataset within each instance. OIDC, tenant isolation, and fine-grained API-key scopes are not implemented.
• Replay historical mappings offline with gl-cli replay. It previews changes by default; use -apply to write them.

See the current limitations and validation record before connecting a production workload. OCSF schema validation in CI, additional storage backends, and broader real-account validation remain on the roadmap.

Architecture

Connectors fetch and normalize vendor alerts. The ingestion engine manages checkpoints and retries. A shared store serves REST, MCP, the query CLI, and the console.

Go · React · TypeScript · Tailwind CSS · SQLite · OCSF 1.6

The store.Store interface separates storage from ingestion and query handlers. PostgreSQL and ClickHouse are potential future implementations, not currently shipped backends.

Development

make test                          # Go tests
make vet                           # Go static checks
npm --prefix web test              # Locale, routing, and UI regression checks
npm --prefix web run build         # TypeScript checks and production console build

• Development and operations — configuration, API, deployment, and validation records; currently in Chinese.
• Connector guide — add a provider, implement mapping, and classify failures.
• Fixture guide — synthetic samples and redaction rules.

Issues with reproducible samples and connector contributions are welcome. Remove credentials and sensitive customer data before sharing payloads.

License

Apache License 2.0. See NOTICE for attribution.

Cloud-provider names and trademarks belong to their respective owners. Embedded brand icons use theSVG and Devicon, both under the MIT license.