s1ctl 是一个 Go 语言编写的 CLI 工具和 SDK，通过配置即代码和漂移检测能力将 SentinelOne Singularity 安全平台的全面管理自动化。
# s1ctl
**以代码方式操作 SentinelOne Singularity Platform —— 适用于*任何*租户。**
[文档](https://s1.danny.vn) · [目录](docs/design/catalog.md) · [版本发布](https://github.com/dannyota/s1ctl/releases)
一个单一的 Go 二进制文件**以及**可导入的 Go SDK，涵盖了 REST Management
API (v2.1)、Singularity Data Lake (REST + GraphQL) 以及四个 GraphQL 域
(alerts、xSPM、cloud security、DLP)。其核心循环是**拉取实时状态 →
审查 `git diff` → 推送回去** —— 一个协调引擎，覆盖所有控制层面，
并使用 `drift` 进行验证。它是**租户中立**的（没有硬编码内容；一切都
来自配置），并且同时为人类和 LLM agent 设计：具有确定性的
flags，到处都是 `--json`，清晰的 `--help`，以及内置的 agent 操作
指南（`s1ctl skill`）。
## 功能介绍
- **配置即代码** — 跨越 11 个控制层面的 `pull` → `git diff` → `push`
(exclusions、blocklist、rules、firewall、network quarantine、device control、
sites、groups、tags、locations、cloud policies)，由一个引擎进行协调，
该引擎会跳过未更改的对象，并在失败时以非零状态退出。
- **漂移检测** — `s1ctl drift` 将提交的配置与实时状态进行比较，如果有任何差异，则以非零状态退出。将其接入 CI 以捕获
控制台侧的更改。
- **全平台管理** — agents（36 个操作）、threats（18 个动词）、
alerts、sites、groups、accounts、policies、users、service users、RBAC roles、
settings（8 个类别）、upgrade policies、filters、locations、tag rules、
maintenance windows、remote operations（scripts、approvals、guardrails）、
reports、IOCs 等。
- **云和漏洞管理** — cloud policies、CNS custom rules
(create、evaluate Rego)、DLP rules 和 classifications、xSPM
misconfigurations 和 vulnerabilities（包含 notes、assignment、history、CVE
queries、stats 和 CSV 导出）。
- **数据湖** — powerquery、basic/facet/timeseries/numeric 查询、event
ingestion、file management、dashboards 和 saved searches。
- **专为 agent 打造** — 硬性只读模式（`S1_READONLY=1`）、
机器可读的命令目录（`s1ctl commands --json`）、本地 mutation
audit log（`~/.s1ctl/audit.jsonl`）、敏感命令的 secret-output 通知，以及用于 LLM agent harnesses 的内置操作指南（`s1ctl skill` / `s1ctl skill
install`）。
## 安装说明
```
go install danny.vn/s1/cmd/s1ctl@latest
```
要求 Go ≥ 1.26。预编译的二进制文件（linux/macOS/windows，amd64/arm64）
可在 [版本发布](https://github.com/dannyota/s1ctl/releases) 页面获取。
## 快速开始
```
s1ctl config init # interactive config wizard
s1ctl doctor # verify auth + API reach
s1ctl commands --json # discover every verb
```
将 `S1_CONSOLE_URL` 和 `S1_TOKEN` 设置为环境变量，或者让
向导写入 `~/.s1ctl/config.yaml`。
## CLI 用法
```
# 读取
s1ctl agents list --site-id 000000 --json
s1ctl threats list --status active --all
s1ctl alerts list --json
s1ctl vulnerabilities cves --json
s1ctl datalake powerquery --query "endpoint.name contains 'srv'" --from 24h
# Mutate（先 dry-run，使用 --yes 应用）
s1ctl agents isolate 000000 # preview
s1ctl agents isolate 000000 --yes # apply
s1ctl threats mitigate 000000 --action remediate --yes
# Config-as-code
s1ctl firewall pull --out firewall/ # snapshot live rules
git diff firewall/ # review
s1ctl firewall push --dir firewall/ --yes # deploy creates + updates
s1ctl drift # verify: exit 0 = clean
```
每个读取命令都支持 `--json` 和 `--output csv`。
## Go SDK
三个可独立导入的包 —— 纯 API，类型化结构体，无文件 I/O：
```
import "danny.vn/s1/mgmt"
client := mgmt.NewClient("https://your-console.sentinelone.net", token)
agents, _, err := client.AgentsList(ctx, nil)
```
```
import "danny.vn/s1/graphql"
client := graphql.NewClient("https://your-console.sentinelone.net", token)
alerts, err := client.AlertsList(ctx, &graphql.ListParams{First: 10})
cves, err := client.CvesList(ctx, nil, nil, &graphql.CvePage{First: 50})
```
```
import "danny.vn/s1/sdl"
client := sdl.NewClient("https://your-sdl-host.sentinelone.net", token)
resp, err := client.PowerQuery(ctx, &sdl.PowerQueryRequest{
Query: "endpoint.name contains 'srv'", StartTime: "24h",
})
```
## API 覆盖范围
| 控制层面 | Package | 方法 | CLI 命令组 |
|---------|---------|---------|------------|
| REST MGMT v2.1 | `danny.vn/s1/mgmt` | 250+ | agents, threats, sites, groups, accounts, policies, exclusions, blocklist, rules, settings, users, service-users, roles, firewall, network, devicecontrol, reports, tags, activities, iocs, remoteops, filters, locations, tag-rules, maintenance, upgrade-policies, updates, applications, detection-library, ranger-ad |
| SDL (Data Lake) | `danny.vn/s1/sdl` | 20+ | datalake (powerquery, query, numeric, facet, timeseries, ingest, files, dashboards, saved-queries) |
| GraphQL | `danny.vn/s1/graphql` | 80+ | alerts, misconfigurations, vulnerabilities, cloud-policies, cloud-rules, dlp, assets |
跨越 48 个组的 370 多个 CLI 命令。运行 `s1ctl commands --json` 获取
完整的实时目录。
## Agent 集成
```
s1ctl skill # print the embedded operating guide
s1ctl skill --json # structured {name, description, body}
s1ctl skill install # write to ~/.claude/skills/s1ctl/ for auto-detection
```
该指南涵盖了 mutation 流程、配置即代码循环、secret-output
约定、自我发现命令以及常用方案。
## 文档
完整文档请访问 [s1.danny.vn](https://s1.danny.vn)。
## License
MIT