hik-connect-team-skill

Hik-Connect for Teams (HCT) Developer Skills. Integrates a series of skills for managing and controlling HCT devices, including resource management, access c...

Security Scan

The skill largely does what it says (Hik-Connect Team device management) but there are inconsistencies and a few risky behaviors you should review before installing (notably a mismatch between declared requirements and the runtime docs, and automatic config-file reading / a bundled webhook server).

Purpose & Capability

The code files and SKILL.md align with the stated purpose: resource management, video capture/streaming, ACS control, and webhook-based alarm push for Hik-Connect for Teams. However the registry metadata lists no required environment variables while the SKILL.md and module metadata clearly require HIK_CONNECT_TEAM_OPENAPI_APP_KEY and HIK_CONNECT_TEAM_OPENAPI_SECRET_KEY — a mismatch that could lead to surprise behavior at runtime.

Instruction Scope

Runtime instructions and scripts stay within the stated domain (calling HCTOpen APIs, obtaining tokens, caching tokens, and optionally running a local webhook server). They explicitly read credentials from environment variables and (as a fallback) from OpenClaw config files (~/.openclaw/*.json). Reading those config files is justified for fallback, but it does access user config paths and therefore can obtain credentials from disk if env vars are not set — the SKILL.md documents this, but you should confirm it only reads the declared channel entry (the docs claim it only reads channels.hik_connect_team_openapi).

Install Mechanism

There is no install spec — this is an instruction-and-code bundle. That is lower-risk than arbitrary download/install steps. The package includes Python scripts and a Node.js webhook server (server.js) but does not attempt to fetch or execute external installers. The README warns Node is required for the webhook service.

Credentials

The functional credential needs are proportional (two Hik-Connect OpenAPI credentials + optional token cache flags). However the declared registry requirements are empty while SKILL.md and module metadata require HIK_CONNECT_TEAM_OPENAPI_APP_KEY and HIK_CONNECT_TEAM_OPENAPI_SECRET_KEY — this discrepancy is concerning. Also the code will read ~/.openclaw/*.json as fallback; if those files contain other sensitive channel entries, a misconfigured implementation could surface unintended secrets. Token caching in /tmp and suggested .env usage are documented, but confirm token_manager.py behavior before running.

Persistence & Privilege

The skill does not request always:true and does not auto-enable itself. It will only run when you invoke its scripts or explicitly start its webhook server. The Webhook module includes a Node server intended to be started by the user (binds port 3090 in documentation) — this is expected for webhook functionality but is a potential exposure if started on a public interface without proper network controls.

What to consider before installing

This package appears to implement what it claims, but review these items before using: 1) Registry metadata omission: the registry lists no required env vars but the code requires HIK_CONNECT_TEAM_OPENAPI_APP_KEY and HIK_CONNECT_TEAM_OPENAPI_SECRET_KEY — set env vars or inspect token_manager.py to understand fallback behavior. 2) Inspect lib/token_manager.py and modules/*/scripts/server.js for any unexpected network calls, logging, or credential handling (these are the highest-risk files). 3) If you don't want this skill to read credentials from disk, ensure the exact OpenClaw config files (~/.openclaw/config.json, gateway/config.json, channels.json) do not contain sensitive keys, or set the env vars instead. 4) If you enable the Alarm webhook (server.js), run it in a controlled network environment (do not expose port 3090 publicly without a reverse proxy and TLS), and examine package.json/server.js for any third-party callbacks or forwarding logic. 5) Create limited-permission Hik-Connect app credentials for testing, rotate keys regularly, and consider disabling token caching during initial testing (HIK_CONNECT_TEAM_TOKEN_CACHE=0). If you want greater assurance, ask the author for an explicit list of file access and outbound endpoints or provide the full token_manager.py and server.js for manual review.

Hik-Connect Team Skills

1. Introduction

Hik-Connect_Team_Skills is a full-featured integration Skills designed specifically for Hik-Connect for Teams (HCT) developers. Based on the HCTOpen OpenAPI system, it encapsulates core capabilities from basic resource management to advanced alarm push through Python scripts.

This Skills adopts a modular design with built-in automated Token maintenance mechanisms, dynamic path searching, and standardized error handling, aiming to help developers quickly build HCT-based automated O&M, security monitoring, and business integration systems.

---

2. Core Modules Deep Dive

This Skills consists of five core sub-modules, each providing deep support for specific business scenarios:

Module Name	Core Functions	Core Scripts	Applicable Scenarios
📦 Resource Management	Device discovery, detail acquisition, channel enumeration	list_devices.py<br>device_detail.py<br>device_channels.py<br>list_doors.py	Asset inventory, obtaining device serial numbers and channel IDs, access control resources, synchronizing organizational structure resources.
🚪 Access Control (ACS)	Remote open/close, normally open/normally closed control	acs_control.py	Remote office collaboration, unattended entrance management, access control linkage in emergencies.
📸 Device Capture	Real-time trigger capture, obtain image URL	capture_pic.py	Anomaly verification, real-time screen preview, manual secondary verification of AI recognition results.
🎥 Video Streaming	Obtain real-time video stream	get_video_url.py	Real-time monitoring embedding, remote video inspection, third-party monitoring large screen integration.
🔔 Alarm Push (Alarm)	Webhook subscription, fine-grained event management	webhook_manager.py<br>event_manager.py	Real-time alarm notification, third-party system integration (e.g., Feishu/DingTalk robots).

---

3. Environment Preparation and Global Configuration

3.1 Credential Configuration

Before using any module, credentials must be configured. The system supports two methods:

Method A: Environment Variables (Recommended)

# Required: Obtain from Hik-Connect HCT Developer Platform
export HIK_CONNECT_TEAM_OPENAPI_APP_KEY="Your Hik-Connect Team OpenAPI AppKey"
export HIK_CONNECT_TEAM_OPENAPI_SECRET_KEY="Your Hik-Connect Team OpenAPI SecretKey"
# Note: API domain is automatically obtained from token response (no longer required)

# Optional: Token cache configuration (enabled by default to reduce API call frequency)
export HIK_CONNECT_TEAM_TOKEN_CACHE="1"  # 1=Enabled, 0=Disabled

Method B: OpenClaw Config Files (Fallback)

If environment variables are not set, the system will automatically search for credentials in OpenClaw config files:

Config search order (first found wins):
1. ~/.openclaw/config.json
2. ~/.openclaw/gateway/config.json
3. ~/.openclaw/channels.json

Config format:

{
  "channels": {
    "hik_connect_team_openapi": {
      "appKey": "Your Hik-Connect Team OpenAPI AppKey",
      "secretKey": "Your Hik-Connect Team OpenAPI SecretKey",
      "enabled": true
    }
  }
}

Recommended: Save to ~/.openclaw/channels.json — This is the dedicated file for channel credentials.

⚠️ Security Note: Storing credentials in config files is convenient but introduces some risk. Environment variables are recommended for better security.

3.2 Dependency Installation

This Skills is developed based on Python 3.8+. It is recommended to install necessary dependencies using the following command:

pip3 install requests tabulate pycryptodome Pillow

---

🔒 Config File Reading Details

Credential Priority (Highest to Lowest):

┌─────────────────────────────────────────────────────────────┐
│ 1. Environment Variables (Highest Priority - Recommended)    │
│    ├─ HIK_CONNECT_TEAM_OPENAPI_APP_KEY                              │
│    └─ HIK_CONNECT_TEAM_OPENAPI_SECRET_KEY                           │
│    ✅ Advantage: No config file reading, fully isolated    │
├─────────────────────────────────────────────────────────────┤
│ 2. OpenClaw Config Files (Only when env vars not set)        │
│    ├─ ~/.openclaw/config.json                               │
│    ├─ ~/.openclaw/gateway/config.json                       │
│    └─ ~/.openclaw/channels.json                             │
│    ⚠️ Note: Only reads channels.hik_connect_team_openapi field    │
├─────────────────────────────────────────────────────────────┤

4. Directory Structure Description

Hik-Connect_Team_Skills/
├── SKILL.md                # This guide file (Full-featured integration guide)
├── lib/                    # Core library
│   └── token_manager.py    # Encapsulates HCTOpenClient base class, handles Token refresh, request retries, and path searching
└── modules/                # Functional sub-modules
    ├── Hik-Connect_Team_Resource/  # Resource Management: Devices, channels, details
    ├── Hik-Connect_Team_ACS/       # Access Control: Open/close, normally open/normally closed
    ├── Hik-Connect_Team_Capture/   # Device Capture: Real-time trigger, URL acquisition
    ├── Hik-Connect_Team_Video/     # Video Streaming: Real-time preview address acquisition
    └── Hik-Connect_Team_Alarm/     # Alarm Push: Webhook management, event subscription

---

5. Security and Best Practices

1. Token Security: The Skills automatically caches Tokens locally. Please ensure the security of the running environment to prevent unauthorized reading of cache files in the lib/ directory.
2. HTTPS Mandatory Requirement: All Webhook callbacks from the HCT platform must use HTTPS. It is recommended to use ngrok or cpolar with SSL certificates for secure access.
3. Signature Verification: In the Alarm module, be sure to configure signSecret and implement HMAC-SHA256 signature verification on your receiving end to prevent forged alarm pushes.
4. Error Handling: All scripts return standard JSON format. If success is false, please check the message field for detailed error reasons.

---