锋利的边缘
- 作者仓库星标 0
- 作者更新于 2026年8月24日 23:09
- 作者仓库 skills
- 领域
- 通用
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 88 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @trailofbits · 未声明许可证
- 上下文用量评级
- 低消耗
- 接入复杂程度
- 需简单配置
- 是否需要外部接口密钥
- 不需要
- 兼容的系统
- 未声明(默认跨平台)
- 运行环境要求
- Python
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 读取环境变量
- 网络行为
- 仅限本地
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
第一阶段:表面识别
映射安全相关的 API:身份验证、授权、加密、会话管理、输入验证 确定开发人员的选择点:开发人员可以在哪里选择算法、配置超时、选择模式?查找配置模式:环境变量、配置文件、构造函数参数
第 2 阶段:边缘案例探测
对于每个选择点,询问: 零/空/空:`0`、`""`、`null`、`[]` 会发生什么情况?负值:`-1`是什么意思?无限?错误?类型混淆:不同的安全概念可以互换吗?默认值:默认值安全吗?有记录吗?
第三阶段:威胁建模
考虑三个对手: 恶棍:主动恶意的开发人员或攻击者控制配置 他们可以通过配置禁用安全性吗?他们可以降级算法吗?他们可以注入恶意值吗?
第四阶段:验证结果
对于每个已识别的锋利边缘: 重现滥用情况:编写最少的代码来演示脚枪 验证可利用性:滥用行为是否会造成真正的漏洞?检查文档:是否记录了危险? (文档并不能成为不良设计的借口,但会影响严重性) 测试缓解措施:可以通过合理的努力安全地使用 API 吗?
# Sharp Edges Analysis
Evaluates whether APIs, configurations, and interfaces are resistant to developer misuse. Identifies designs where the "easy path" leads to insecurity.
## When to Use
- Reviewing API or library design decisions
- Auditing configuration schemas for dangerous options
- Evaluating cryptographic API ergonomics
- Assessing authentication/authorization interfaces
- Reviewing any code that exposes security-relevant choices to developers
## When NOT to Use
- Implementation bugs (use standard code review)
- Business logic flaws (use domain-specific analysis)
- Performance optimization (different concern)
## Agent
The `sharp-edges-analyzer` agent runs the full sharp edges analysis workflow autonomously. Use it when you want a dedicated analysis of APIs, configurations, or interfaces for misuse resistance and footgun potential. The agent follows the four-phase workflow (Surface Identification, Edge Case Probing, Threat Modeling, Validate Findings) and reads language-specific references on demand.
## Core Principle
**The pit of success**: Secure usage should be the path of least resistance. If developers must understand cryptography, read documentation carefully, or remember special rules to avoid vulnerabilities, the API has failed.
## Rationalizations to Reject
| Rationalization | Why It's Wrong | Required Action |
|-----------------|----------------|-----------------|
| "It's documented" | Developers don't read docs under deadline pressure | Make the secure choice the default or only option |
| "Advanced users need flexibility" | Flexibility creates footguns; most "advanced" usage is copy-paste | Provide safe high-level APIs; hide primitives |
| "It's the developer's responsibility" | Blame-shifting; you designed the footgun | Remove the footgun or make it impossible to misuse |
| "Nobody would actually do that" | Developers do everything imaginable under pressure | Assume maximum developer confusion |
| "It's just a configuration option" | Config is code; wrong configs ship to production | Validate configs; reject dangerous combinations |
| "We need backwards compatibility" | Insecure defaults can't be grandfather-claused | Deprecate loudly; force migration |
## Sharp Edge Categories
### 1. Algorithm/Mode Selection Footguns
APIs that let developers choose algorithms invite choosing wrong ones.
**The JWT Pattern** (canonical example):
- Header specifies algorithm: attacker can set `"alg": "none"` to bypass signatures
- Algorithm confusion: RSA public key used as HMAC secret when switching RS256→HS256
- Root cause: Letting untrusted input control security-critical decisions
**Detection patterns:**
- Function parameters like `algorithm`, `mode`, `cipher`, `hash_type`
- Enums/strings selecting cryptographic primitives
- Configuration options for security mechanisms
**Example - PHP password_hash allowing weak algorithms:**
```php
// DANGEROUS: allows crc32, md5, sha1
password_hash($password, PASSWORD_DEFAULT); // Good - no choice
hash($algorithm, $password); // BAD: accepts "crc32"
```
### 2. Dangerous Defaults
Defaults that are insecure, or zero/empty values that disable security.
**The OTP Lifetime Pattern:**
```python
# What happens when lifetime=0?
def verify_otp(code, lifetime=300): # 300 seconds default
if lifetime == 0:
return True # OOPS: 0 means "accept all"?
# Or does it mean "expired immediately"?
```
**Detection patterns:**
- Timeouts/lifetimes that accept 0 (infinite? immediate expiry?)
- Empty strings that bypass checks
- Null values that skip validation
- Boolean defaults that disable security features
- Negative values with undefined semantics
**Questions to ask:**
- What happens with `timeout=0`? `max_attempts=0`? `key=""`?
- Is the default the most secure option?
- Can any default value disable security entirely?
### 3. Primitive vs. Semantic APIs
APIs that expose raw bytes instead of meaningful types invite type confusion.
**The Libsodium vs. Halite Pattern:**
```php
// Libsodium (primitives): bytes are bytes
sodium_crypto_box($message, $nonce, $keypair);
// Easy to: swap nonce/keypair, reuse nonces, use wrong key type
// Halite (semantic): types enforce correct usage
Crypto::seal($message, new EncryptionPublicKey($key));
// Wrong key type = type error, not silent failure
```
**Detection patterns:**
- Functions taking `bytes`, `string`, `[]byte` for distinct security concepts
- Parameters that could be swapped without type errors
- Same type used for keys, nonces, ciphertexts, signatures
**The comparison footgun:**
```go
// Timing-safe comparison looks identical to unsafe
if hmac == expected { } // BAD: timing attack
if hmac.Equal(mac, expected) { } // Good: constant-time
// Same types, different security properties
```
### 4. Configuration Cliffs
One wrong setting creates catastrophic failure, with no warning.
**Detection patterns:**
- Boolean flags that disable security entirely
- String configs that aren't validated
- Combinations of settings that interact dangerously
- Environment variables that override security settings
- Constructor parameters with sensible defaults but no validation (callers can override with insecure values)
**Examples:**
```yaml
# One typo = disaster
verify_ssl: fasle # Typo silently accepted as truthy?
# Magic values
session_timeout: -1 # Does this mean "never expire"?
# Dangerous combinations accepted silently
auth_required: true
bypass_auth_for_health_checks: true
health_check_path: "/" # Oops
```
```php
// Sensible default doesn't protect against bad callers
public function __construct(
public string $hashAlgo = 'sha256', // Good default...
public int $otpLifetime = 120, // ...but accepts md5, 0, etc.
) {}
```
See [config-patterns.md](references/config-patterns.md#unvalidated-constructor-parameters) for detailed patterns.
### 5. Silent Failures
Errors that don't surface, or success that masks failure.
**Detection patterns:**
- Functions returning booleans instead of throwing on security failures
- Empty catch blocks around security operations
- Default values substituted on parse errors
- Verification functions that "succeed" on malformed input
**Examples:**
```python
# Silent bypass
def verify_signature(sig, data, key):
if not key:
return True # No key = skip verification?!
# Return value ignored
signature.verify(data, sig) # Throws on failure
crypto.verify(data, sig) # Returns False on failure
# Developer forgets to check return value
```
### 6. Stringly-Typed Security
Security-critical values as plain strings enable injection and confusion.
**Detection patterns:**
- SQL/commands built from string concatenation
- Permissions as comma-separated strings
- Roles/scopes as arbitrary strings instead of enums
- URLs constructed by joining strings
**The permission accumulation footgun:**
```python
permissions = "read,write"
permissions += ",admin" # Too easy to escalate
# vs. type-safe
permissions = {Permission.READ, Permission.WRITE}
permissions.add(Permission.ADMIN) # At least it's explicit
```
## Analysis Workflow
### Phase 1: Surface Identification
1. **Map security-relevant APIs**: authentication, authorization, cryptography, session management, input validation
2. **Identify developer choice points**: Where can developers select algorithms, configure timeouts, choose modes?
3. **Find configuration schemas**: Environment variables, config files, constructor parameters
### Phase 2: Edge Case Probing
For each choice point, ask:
- **Zero/empty/null**: What happens with `0`, `""`, `null`, `[]`?
- **Negative values**: What does `-1` mean? Infinite? Error?
- **Type confusion**: Can different security concepts be swapped?
- **Default values**: Is the default secure? Is it documented?
- **Error paths**: What happens on invalid input? Silent acceptance?
### Phase 3: Threat Modeling
Consider three adversaries:
1. **The Scoundrel**: Actively malicious developer or attacker controlling config
- Can they disable security via configuration?
- Can they downgrade algorithms?
- Can they inject malicious values?
2. **The Lazy Developer**: Copy-pastes examples, skips documentation
- Will the first example they find be secure?
- Is the path of least resistance secure?
- Do error messages guide toward secure usage?
3. **The Confused Developer**: Misunderstands the API
- Can they swap parameters without type errors?
- Can they use the wrong key/algorithm/mode by accident?
- Are failure modes obvious or silent?
### Phase 4: Validate Findings
For each identified sharp edge:
1. **Reproduce the misuse**: Write minimal code demonstrating the footgun
2. **Verify exploitability**: Does the misuse create a real vulnerability?
3. **Check documentation**: Is the danger documented? (Documentation doesn't excuse bad design, but affects severity)
4. **Test mitigations**: Can the API be used safely with reasonable effort?
If a finding seems questionable, return to Phase 2 and probe more edge cases.
## Severity Classification
| Severity | Criteria | Examples |
|----------|----------|----------|
| Critical | Default or obvious usage is insecure | `verify: false` default; empty password allowed |
| High | Easy misconfiguration breaks security | Algorithm parameter accepts "none" |
| Medium | Unusual but possible misconfiguration | Negative timeout has unexpected meaning |
| Low | Requires deliberate misuse | Obscure parameter combination |
## References
**By category:**
- **Cryptographic APIs**: See [references/crypto-apis.md](references/crypto-apis.md)
- **Configuration Patterns**: See [references/config-patterns.md](references/config-patterns.md)
- **Authentication/Session**: See [references/auth-patterns.md](references/auth-patterns.md)
- **Real-World Case Studies**: See [references/case-studies.md](references/case-studies.md) (OpenSSL, GMP, etc.)
**By language** (general footguns, not crypto-specific):
| Language | Guide |
|----------|-------|
| C/C++ | [references/lang-c.md](references/lang-c.md) |
| Go | [references/lang-go.md](references/lang-go.md) |
| Rust | [references/lang-rust.md](references/lang-rust.md) |
| Swift | [references/lang-swift.md](references/lang-swift.md) |
| Java | [references/lang-java.md](references/lang-java.md) |
| Kotlin | [references/lang-kotlin.md](references/lang-kotlin.md) |
| C# | [references/lang-csharp.md](references/lang-csharp.md) |
| PHP | [references/lang-php.md](references/lang-php.md) |
| JavaScript/TypeScript | [references/lang-javascript.md](references/lang-javascript.md) |
| Python | [references/lang-python.md](references/lang-python.md) |
| Ruby | [references/lang-ruby.md](references/lang-ruby.md) |
See also [references/language-specific.md](references/language-specific.md) for a combined quick reference.
## Quality Checklist
Before concluding analysis:
- [ ] Probed all zero/empty/null edge cases
- [ ] Verified defaults are secure
- [ ] Checked for algorithm/mode selection footguns
- [ ] Tested type confusion between security concepts
- [ ] Considered all three adversary types
- [ ] Verified error paths don't bypass security
- [ ] Checked configuration validation
- [ ] Constructor params validated (not just defaulted) - see [config-patterns.md](references/config-patterns.md#unvalidated-constructor-parameters)
章节与文件索引
按说明文件中的顺序排列。
何时使用
何时不使用
代理
核心原则
拒绝的理由
文件/命令 -> sharp-edges-analyzer · "alg": "none" · algorithm · mode · cipher · hash_type · timeout=0 · max_attempts=0
内容校验值 -> 57d140c7e0a5
当前原文的自动摘译,尚未人工审校。
何时使用
审查 API 或库设计决策 审核配置模式是否存在危险选项 评估加密 API 人体工程学 评估身份验证/授权接口 审查向开发人员公开安全相关选择的任何代码
何时不使用
实现错误(使用标准代码审查) 业务逻辑缺陷(使用特定领域的分析) 性能优化(不同关注点)
代理
sharp-edges-analyzer代理自主运行完整的锐边分析工作流程。当您想要对 API、配置或接口进行专门分析以防止误用和脚枪潜力时,请使用它。该代理遵循四阶段工作流程(表面识别、边缘情况探测、威胁建模、验证结果)并按需读取特定于语言的参考。核心原则
成功的陷阱:安全使用应该是阻力最小的途径。如果开发人员必须了解密码学、仔细阅读文档或记住特殊规则以避免漏洞,那么 API 就失败了。
拒绝的理由
合理化 · 为什么这是错误的 · 需要采取的行动 “已记录在案” · 开发人员在截止日期压力下不会阅读文档 · 将安全选择作为默认或唯一选项 “高级用户需要灵活性” · 灵活性创造了枪口;最“高级”的用法是复制粘贴 · 提供安全的高级 API;隐藏原语“这是开发人员的责任” · 推卸责任;您设计了足枪 · 取下足枪或使其不可能被误用