superior-api-security

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Superior API Security

Superior API Security

Protect the API at the server-side trust boundary while preserving its documented contract. Base controls on the actual actors, resources, business impact, deployment topology, and existing security architecture; do not add security middleware by checklist alone.
在服务器端信任边界保护 API,同时保留其已文档化的契约。应根据实际调用方、资源、业务影响、部署拓扑和现有安全架构制定控制措施;不要仅按检查清单添加安全中间件。

Establish the security contract

建立安全契约

Before changing code, identify:
  • exposed operations, versions, and consumers;
  • public, authenticated, privileged, internal, webhook, and machine-to-machine callers;
  • sensitive resources, properties, actions, and business flows;
  • where identity is established and where authorization is enforced;
  • proxies, gateways, caches, queues, third-party services, and outbound network access;
  • expected traffic, burst behavior, payload size, operation cost, and failure tolerance;
  • security controls already owned by infrastructure versus the application.
Trace the effective request path. Do not assume a gateway, framework default, or client-side check enforces the requirement until configuration and behavior prove it.
修改代码之前,需要识别:
  • 对外暴露的操作、版本和使用方;
  • 公开、需身份认证、特权、内部、Webhook 和机器对机器调用方;
  • 敏感资源、属性、操作和业务流程;
  • 建立身份的位置和执行授权的位置;
  • 代理、网关、缓存、队列、第三方服务和出站网络访问;
  • 预期流量、突发行为、Payload 大小、操作成本和容错能力;
  • 基础设施与应用分别负责的安全控制。
跟踪实际生效的请求路径。在配置和行为能够证明某项要求已得到执行之前,不要假定 Gateway、框架默认行为或客户端检查能够落实该要求。

Select controls from risk

根据风险选择控制措施

Read references/api-security-controls.md for authentication, object/function/property authorization, input and output boundaries, resource consumption, sensitive business flows, SSRF, browser-facing controls, errors, secrets, inventory, and third-party API consumption.
Prioritize controls that prevent a caller from:
  • acting as another identity or outside its granted scope;
  • reading or mutating another subject's object;
  • setting or receiving properties it is not allowed to access;
  • invoking privileged operations or skipping workflow invariants;
  • exhausting compute, storage, bandwidth, paid integrations, or scarce inventory;
  • making the server contact an unintended destination;
  • learning sensitive internals through responses, logs, timing, or metadata.
Preserve maintained identity, cryptography, schema-validation, and secret-management libraries. Do not invent token formats, signing schemes, password storage, or encryption protocols.
Read references/session-token-and-webhook-security.md when sessions, bearer tokens, refresh or reset credentials, API keys, signed webhooks, key rotation, revocation, or replay resistance are in scope.
阅读 references/api-security-controls.md,了解身份认证、对象/函数/属性授权、输入与输出边界、资源消耗、敏感业务流程、SSRF、面向浏览器的控制措施、错误处理、密钥管理、资产清单和第三方 API 消费。
优先选择能够防止调用方出现以下行为的控制措施:
  • 冒充其他身份或执行超出其授权范围的操作;
  • 读取或修改其他主体的对象;
  • 设置或获取其无权访问的属性;
  • 调用特权操作或绕过工作流不变量;
  • 耗尽计算资源、存储、带宽、付费集成额度或稀缺库存;
  • 使服务器联系非预期目标;
  • 通过响应、日志、时序或元数据获知敏感内部信息。
保留持续维护的身份管理、密码学、Schema 验证和密钥管理库。不要自行设计 Token 格式、签名方案、口令存储方式或加密协议。
当会话、Bearer Token、刷新或重置凭据、API Key、签名 Webhook、密钥轮换、吊销或重放防护属于工作范围时,阅读 references/session-token-and-webhook-security.md。

Apply rate and abuse controls deliberately

有意实施速率与滥用控制

Read references/rate-limiting-and-abuse-controls.md whenever rate limiting, throttling, quotas, concurrency limits, credential attacks, scraping, spam, enumeration, costly operations, or sensitive business-flow automation is in scope.
A useful limit defines all of the following:
  • the operation and harm being controlled;
  • the identity dimensions used for accounting;
  • sustained allowance, burst allowance, concurrency, and cost weighting;
  • where counters live and how distributed instances coordinate;
  • behavior when the limiter or counter store fails;
  • the rejection contract, observability, exemptions, and recovery path;
  • tests proving both enforcement and legitimate burst tolerance.
An IP-only request count is rarely sufficient for authenticated or distributed abuse. Request rate also does not bound payload size, query complexity, batch size, execution time, downstream cost, or concurrent work.
当速率限制、节流、配额、并发限制、凭据攻击、抓取、垃圾信息、枚举、高成本操作或敏感业务流程自动化属于工作范围时,阅读 references/rate-limiting-and-abuse-controls.md。
有效的限制需要定义以下各项:
  • 所控制的操作和危害;
  • 用于计数的身份维度;
  • 持续限额、突发限额、并发度和成本权重;
  • 计数器的存放位置及分布式实例之间的协调方式;
  • 限流器或计数器存储失败时的行为;
  • 拒绝契约、可观测性、豁免机制和恢复路径;
  • 既证明限制已生效,也证明合法突发流量能够被容忍的测试。
仅依赖 IP 的请求计数通常不足以应对已认证滥用或分布式滥用。请求速率也无法限制 Payload 大小、查询复杂度、批处理规模、执行时间、下游成本或并发工作量。

Keep responses and telemetry safe

保持响应和遥测安全

  • Use established HTTP semantics and the project's error schema. Return
    429 Too Many Requests
    for an application-level rate rejection and include
    Retry-After
    when a meaningful retry time is known.
  • Give clients stable, actionable error identifiers without exposing stack traces, secrets, queries, internal hostnames, token contents, or authorization policy details.
  • Log security-relevant outcomes with request or trace correlation, actor and tenant identifiers where permitted, control decisions, and sanitized reason codes.
  • Do not log credentials, session tokens, API keys, raw authorization headers, password-reset artifacts, or unnecessary sensitive payloads.
  • Separate client-visible detail from diagnostic detail and follow the repository's privacy and retention rules.
  • 使用既定的 HTTP 语义和项目的错误 Schema。应用级速率拒绝应返回
    429 Too Many Requests
    ,并在能够确定有意义的重试时间时包含
    Retry-After
    。
  • 向客户端提供稳定且可操作的错误标识,同时避免暴露堆栈跟踪、密钥、查询、内部主机名、Token 内容或授权策略细节。
  • 记录与安全相关的结果,并包含请求或 Trace 关联信息、在允许情况下包含参与者与租户标识、控制决策以及经过清理的原因码。
  • 不要记录凭据、会话 Token、API Key、原始 Authorization Header、口令重置产物或不必要的敏感 Payload。
  • 区分客户端可见详情和诊断详情,并遵循仓库的隐私与保留规则。

Verify before claiming protection

在宣称已获得保护之前进行验证

Read references/security-verification.md for a threat-driven test matrix, including negative authorization, token validation, schema mutation, resource limits, limiter behavior, concurrency, SSRF, error disclosure, and proxy-boundary checks.
Security completion requires evidence at the effective enforcement point. Run the narrowest meaningful automated tests plus configuration or integration checks that exercise the deployed path. For design-only work, label tests as a proposed verification plan rather than evidence of protection. Report controls enforced elsewhere, assumptions not verified, rollout risk, and monitoring needed after release.
阅读 references/security-verification.md,了解威胁驱动的测试矩阵,包括负向授权、Token 验证、Schema 变异、资源限制、限流器行为、并发、SSRF、错误信息披露和代理边界检查。
安全工作的完成需要在实际生效的执行点提供证据。应运行范围最窄但仍有意义的自动化测试,以及能够覆盖已部署路径的配置或集成检查。如果仅完成设计,应将测试标注为拟议的验证计划,而不能将其视为已获得保护的证据。报告由其他位置执行的控制措施、尚未验证的假设、发布风险和上线后所需的监控。

Combine skills narrowly

谨慎组合 Skill

  • Use
    superior-code-review
    when security is one risk area in a broader diff, branch, or pull-request review.
  • Use
    superior-logic
    when the work also changes business invariants, persistence, transactions, idempotency, or domain behavior.
  • Use
    superior-database
    when enforcement depends on tenant-scoped schema, constraints, query ownership, indexes, migrations, or sensitive-data storage.
  • Use
    superior-performance
    when security-related resource controls require representative capacity, latency, or saturation measurement.
  • Use
    superior-delivery
    when the security boundary is owned by pipeline identity, artifact provenance, publication, or deployment credentials.
  • Use
    superior-reliability
    when abuse, dependency failure, or recovery must preserve an explicit availability objective.
  • Use
    superior-testing
    when negative-security fixtures, isolation, concurrency, or deployed-boundary test design is a primary concern.
  • Use
    superior-docs
    when the security model, public contract, operational configuration, or incident-relevant procedure changes durably.
  • Use
    superior-lean
    to avoid unnecessary security machinery, but never simplify away a control required by the identified risk.
Do not broaden a security review into unrelated penetration testing, infrastructure changes, or production traffic experiments without explicit authorization.
  • 当安全是更广泛的代码变更、分支或 Pull Request 审查中的一项风险领域时,使用
    superior-code-review
    。
  • 当工作还涉及更改业务不变量、持久化、事务、幂等性或领域行为时,使用
    superior-logic
    。
  • 当执行依赖于租户范围的 Schema、约束、查询所有权、索引、迁移或敏感数据存储时,使用
    superior-database
    。
  • 当安全相关资源控制需要测量有代表性的容量、延迟或饱和度时,使用
    superior-performance
    。
  • 当安全边界由流水线身份、Artifact 来源、发布或部署凭据负责时,使用
    superior-delivery
    。
  • 当滥用、依赖故障或恢复必须保持明确的可用性目标时,使用
    superior-reliability
    。
  • 当安全负向测试夹具、隔离、并发或部署边界测试设计是主要关注点时,使用
    superior-testing
    。
  • 当安全模型、公共契约、运维配置或与事件相关的流程需要持久变更时,使用
    superior-docs
    。
  • 使用
    superior-lean
    避免不必要的安全机制,但绝不能简化掉已识别风险所必需的控制措施。
未经明确授权,不要将安全审查扩展到无关的渗透测试、基础设施变更或生产流量实验。