【系统架构设计百科】API 安全：从注入攻击到供应链威胁

query {
  user(id: "1") {
    posts {
      comments {
        author {
          posts {
            comments {
              author {
                posts { title }
              }
            }
          }
        }
      }
    }
  }
}

// 有漏洞的实现：只验证了令牌，没有验证所有权
func GetOrder(w http.ResponseWriter, r *http.Request) {
    orderID := chi.URLParam(r, "orderID")
    order, err := db.GetOrderByID(orderID)
    if err != nil {
        http.Error(w, "not found", http.StatusNotFound)
        return
    }
    json.NewEncoder(w).Encode(order)
}

// 安全的实现：在查询条件中绑定当前用户
func GetOrder(w http.ResponseWriter, r *http.Request) {
    orderID := chi.URLParam(r, "orderID")
    userID := auth.GetUserID(r.Context()) // 从令牌中提取用户 ID

    order, err := db.GetOrderByUserAndID(userID, orderID)
    if err != nil {
        // 不区分"不存在"和"无权限"，统一返回 404
        http.Error(w, "not found", http.StatusNotFound)
        return
    }
    json.NewEncoder(w).Encode(order)
}

-- 有漏洞的查询
SELECT * FROM orders WHERE id = ?;

-- 安全的查询：强制绑定 user_id
SELECT * FROM orders WHERE id = ? AND user_id = ?;

// 资源所有权中间件
func OwnershipMiddleware(resourceType string) func(http.Handler) http.Handler {
    return func(next http.Handler) http.Handler {
        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
            userID := auth.GetUserID(r.Context())
            resourceID := chi.URLParam(r, "id")

            hasAccess, err := authz.CheckOwnership(r.Context(), authz.CheckInput{
                UserID:       userID,
                ResourceType: resourceType,
                ResourceID:   resourceID,
                Action:       r.Method,
            })
            if err != nil || !hasAccess {
                http.Error(w, "not found", http.StatusNotFound)
                return
            }
            next.ServeHTTP(w, r)
        })
    }
}

// 路由注册
r.Route("/api/v1/orders/{id}", func(r chi.Router) {
    r.Use(OwnershipMiddleware("order"))
    r.Get("/", GetOrder)
    r.Put("/", UpdateOrder)
    r.Delete("/", DeleteOrder)
})

// 多租户资源访问：同时绑定租户 ID 和用户 ID
func GetTenantResource(w http.ResponseWriter, r *http.Request) {
    tenantID := auth.GetTenantID(r.Context())
    userID := auth.GetUserID(r.Context())
    resourceID := chi.URLParam(r, "id")

    resource, err := db.GetResource(r.Context(), tenantID, userID, resourceID)
    if err != nil {
        http.Error(w, "not found", http.StatusNotFound)
        return
    }
    json.NewEncoder(w).Encode(resource)
}

SELECT * FROM resources
WHERE id = ? AND tenant_id = ? AND (owner_id = ? OR ? IN (
    SELECT user_id FROM resource_shares WHERE resource_id = resources.id
));

import (
    "net"
    "net/url"
    "strings"
)

var privateRanges = []net.IPNet{
    parseCIDR("10.0.0.0/8"),
    parseCIDR("172.16.0.0/12"),
    parseCIDR("192.168.0.0/16"),
    parseCIDR("169.254.0.0/16"),  // 链路本地地址
    parseCIDR("127.0.0.0/8"),     // 回环地址
    parseCIDR("::1/128"),         // IPv6 回环
    parseCIDR("fc00::/7"),        // IPv6 唯一本地地址
    parseCIDR("fe80::/10"),       // IPv6 链路本地地址
}

func parseCIDR(cidr string) net.IPNet {
    _, network, _ := net.ParseCIDR(cidr)
    return *network
}

// ValidateExternalURL 校验 URL 是否指向外部地址
func ValidateExternalURL(rawURL string) error {
    parsed, err := url.Parse(rawURL)
    if err != nil {
        return fmt.Errorf("URL 格式无效")
    }

    // 只允许 HTTPS
    if parsed.Scheme != "https" {
        return fmt.Errorf("仅允许 HTTPS 协议")
    }

    // 解析主机名为 IP 地址
    host := parsed.Hostname()
    ips, err := net.LookupIP(host)
    if err != nil {
        return fmt.Errorf("无法解析主机名: %s", host)
    }

    // 检查所有解析出的 IP 是否为内网地址
    for _, ip := range ips {
        for _, privateRange := range privateRanges {
            if privateRange.Contains(ip) {
                return fmt.Errorf("不允许访问内网地址")
            }
        }
    }

    return nil
}

// 安全的 HTTP 客户端：在连接阶段检查目标 IP
func NewSafeHTTPClient() *http.Client {
    transport := &http.Transport{
        DialContext: func(ctx context.Context, network, addr string) (net.Conn, error) {
            host, port, err := net.SplitHostPort(addr)
            if err != nil {
                return nil, err
            }

            // 在连接阶段再次解析并校验 IP
            ips, err := net.DefaultResolver.LookupIPAddr(ctx, host)
            if err != nil {
                return nil, err
            }

            for _, ip := range ips {
                for _, privateRange := range privateRanges {
                    if privateRange.Contains(ip.IP) {
                        return nil, fmt.Errorf("连接目标为内网地址，已拒绝")
                    }
                }
            }

            // 使用解析后的 IP 直接连接，避免二次解析
            dialer := &net.Dialer{Timeout: 10 * time.Second}
            return dialer.DialContext(ctx, network, net.JoinHostPort(ips[0].IP.String(), port))
        },
    }

    return &http.Client{
        Transport: transport,
        Timeout:   30 * time.Second,
        CheckRedirect: func(req *http.Request, via []*http.Request) error {
            if len(via) >= 3 {
                return fmt.Errorf("重定向次数超过限制")
            }
            // 对重定向目标也做 URL 校验
            return ValidateExternalURL(req.URL.String())
        },
    }
}

apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: webhook-sender-egress
spec:
  podSelector:
    matchLabels:
      app: webhook-sender
  policyTypes:
    - Egress
  egress:
    - to:
        - ipBlock:
            cidr: 0.0.0.0/0
            except:
              - 10.0.0.0/8
              - 172.16.0.0/12
              - 192.168.0.0/16
              - 169.254.0.0/16
      ports:
        - protocol: TCP
          port: 443
    - to:
        - namespaceSelector: {}
          podSelector:
            matchLabels:
              app: kube-dns
      ports:
        - protocol: UDP
          port: 53

// 有漏洞的代码：动态排序字段
func ListUsers(sortBy string) ([]User, error) {
    // sortBy 来自用户输入，直接拼接到 SQL 中
    query := fmt.Sprintf("SELECT * FROM users ORDER BY %s", sortBy)
    return db.Query(query)
}
// 攻击输入：sortBy = "1; DROP TABLE users;--"

// 安全的实现：白名单校验排序字段
var allowedSortFields = map[string]string{
    "name":       "name",
    "created_at": "created_at",
    "email":      "email",
}

func ListUsers(sortBy string) ([]User, error) {
    column, ok := allowedSortFields[sortBy]
    if !ok {
        column = "created_at" // 默认排序
    }

    query := fmt.Sprintf("SELECT id, name, email FROM users ORDER BY %s", column)
    return db.Query(query)
}

// 正常登录请求
{"username": "admin", "password": "secret123"}

// 注入攻击：使用 $ne 操作符绕过密码校验
{"username": "admin", "password": {"$ne": ""}}

type LoginRequest struct {
    Username string `json:"username" validate:"required,alphanum,min=3,max=32"`
    Password string `json:"password" validate:"required,min=8,max=128"`
}

func Login(w http.ResponseWriter, r *http.Request) {
    var req LoginRequest
    if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
        http.Error(w, "请求格式错误", http.StatusBadRequest)
        return
    }

    // 使用 validator 库做结构体验证
    if err := validate.Struct(req); err != nil {
        http.Error(w, "参数验证失败", http.StatusBadRequest)
        return
    }

    // req.Password 已经被确认为 string 类型，不可能是 MongoDB 操作符
    user, err := db.FindUser(r.Context(), req.Username, hashPassword(req.Password))
    // ...
}

[
  {"query": "{ user(id: \"1\") { email } }"},
  {"query": "{ user(id: \"2\") { email } }"},
  {"query": "{ user(id: \"3\") { email } }"},
  // ... 重复 10000 次
]

// GraphQL 安全配置示例（使用 gqlgen 框架）
func NewGraphQLHandler() http.Handler {
    srv := handler.NewDefaultServer(generated.NewExecutableSchema(generated.Config{
        Resolvers: &resolver.Resolver{},
    }))

    // 限制查询深度
    srv.Use(extension.FixedComplexityLimit(200))

    // 自定义复杂度计算
    srv.AroundFields(func(ctx context.Context, next graphql.Resolver) (interface{}, error) {
        fc := graphql.GetFieldContext(ctx)
        if fc.IsResolver {
            complexity := graphql.GetOperationContext(ctx).Stats.Complexity
            if complexity > 500 {
                return nil, fmt.Errorf("查询复杂度超过限制")
            }
        }
        return next(ctx)
    })

    // 禁用内省查询（生产环境）
    srv.Use(apollotracing.Tracer{})

    return srv
}

// 多维度速率限制配置
type RateLimitConfig struct {
    // 全局限制：保护基础设施
    GlobalRPS int `yaml:"global_rps"` // 每秒请求数

    // 用户级限制：防止单用户滥用
    PerUserRPS    int `yaml:"per_user_rps"`
    PerUserBurst  int `yaml:"per_user_burst"`

    // 接口级限制：保护高成本接口
    EndpointLimits map[string]EndpointLimit `yaml:"endpoint_limits"`
}

type EndpointLimit struct {
    Path      string `yaml:"path"`
    RPS       int    `yaml:"rps"`
    BurstSize int    `yaml:"burst_size"`
    // 针对敏感接口的额外限制
    PerIPLimit    int  `yaml:"per_ip_limit"`
    RequireCaptcha bool `yaml:"require_captcha"` // 超限后要求验证码
}

rate_limits:
  global_rps: 10000
  per_user_rps: 100
  per_user_burst: 200
  endpoint_limits:
    login:
      path: "/api/v1/auth/login"
      rps: 5
      burst_size: 10
      per_ip_limit: 3
      require_captcha: true
    password_reset:
      path: "/api/v1/auth/reset-password"
      rps: 2
      burst_size: 5
      per_ip_limit: 1
    export:
      path: "/api/v1/data/export"
      rps: 1
      burst_size: 2

# OpenAPI 定义中的安全相关约束
paths:
  /api/v1/users/{userId}:
    get:
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
            format: uuid
            pattern: "^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserResponse"
                # 响应 Schema 也要定义，防止数据过度暴露

{
  "filters": {
    "advanced": {
      "conditions": [
        {"field": "name", "op": "eq", "value": "'; DROP TABLE users;--"}
      ]
    }
  }
}

# .spectral.yaml -- API 安全规约规则
extends: ["spectral:oas"]
rules:
  # 所有接口必须定义认证方式
  operation-security-defined:
    description: "每个操作必须定义安全方案"
    given: "$.paths[*][get,post,put,delete,patch]"
    then:
      field: security
      function: truthy
    severity: error

  # 禁止在 URL 中传递敏感参数
  no-sensitive-query-params:
    description: "敏感参数不应出现在查询字符串中"
    given: "$.paths[*][*].parameters[?(@.in == 'query')]"
    then:
      field: name
      function: pattern
      functionOptions:
        notMatch: "(?i)(password|token|secret|key|credential|api.?key)"
    severity: error

  # 响应必须定义 Schema，防止数据过度暴露
  response-schema-defined:
    description: "响应必须定义 Schema"
    given: "$.paths[*][*].responses[*].content[*]"
    then:
      field: schema
      function: truthy
    severity: warn

  # 路径参数必须有格式约束
  path-param-format:
    description: "路径参数必须定义 format 或 pattern"
    given: "$.paths[*].parameters[?(@.in == 'path')].schema"
    then:
      function: schema
      functionOptions:
        schema:
          anyOf:
            - required: ["format"]
            - required: ["pattern"]
    severity: warn

# GitHub Actions 中的 API 安全检查
name: API Security Lint
on:
  pull_request:
    paths:
      - "api/**/*.yaml"
      - "api/**/*.json"

jobs:
  spectral-lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run Spectral
        uses: stoplightio/spectral-action@latest
        with:
          file_glob: "api/**/*.yaml"
          spectral_ruleset: ".spectral.yaml"

// 安全契约测试示例
func TestOrderAPI_AuthorizationContract(t *testing.T) {
    tests := []struct {
        name       string
        userID     string
        orderOwner string
        wantStatus int
    }{
        {
            name:       "用户访问自己的订单应返回 200",
            userID:     "user-001",
            orderOwner: "user-001",
            wantStatus: http.StatusOK,
        },
        {
            name:       "用户访问他人的订单应返回 404",
            userID:     "user-001",
            orderOwner: "user-002",
            wantStatus: http.StatusNotFound,
        },
        {
            name:       "无认证请求应返回 401",
            userID:     "",
            orderOwner: "user-001",
            wantStatus: http.StatusUnauthorized,
        },
    }

    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            order := createTestOrder(t, tt.orderOwner)
            req := newRequest(t, "GET", "/api/v1/orders/"+order.ID)
            if tt.userID != "" {
                req.Header.Set("Authorization", "Bearer "+generateToken(tt.userID))
            }
            resp := executeRequest(req)
            if resp.StatusCode != tt.wantStatus {
                t.Errorf("期望状态码 %d，实际 %d", tt.wantStatus, resp.StatusCode)
            }
        })
    }
}

// SSRF 防御契约测试
func TestWebhookAPI_SSRFProtection(t *testing.T) {
    tests := []struct {
        name       string
        url        string
        wantStatus int
    }{
        {"内网地址应被拒绝", "http://169.254.169.254/latest/meta-data/", http.StatusBadRequest},
        {"回环地址应被拒绝", "http://127.0.0.1:8080/internal", http.StatusBadRequest},
        {"私有地址应被拒绝", "http://10.0.0.1/admin", http.StatusBadRequest},
        {"非 HTTPS 应被拒绝", "http://example.com/webhook", http.StatusBadRequest},
        {"合法 HTTPS 地址应通过", "https://example.com/webhook", http.StatusCreated},
    }

    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            body := fmt.Sprintf(`{"url": "%s", "events": ["order.created"]}`, tt.url)
            req := newAuthRequest(t, "POST", "/api/v1/webhooks", body)
            resp := executeRequest(req)
            if resp.StatusCode != tt.wantStatus {
                t.Errorf("URL %s：期望状态码 %d，实际 %d", tt.url, tt.wantStatus, resp.StatusCode)
            }
        })
    }
}

# CI/CD 安全扫描流水线
name: Security Pipeline
on: [push, pull_request]

jobs:
  sast:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run gosec (Go 安全扫描)
        uses: securego/gosec@master
        with:
          args: "-exclude=G104 ./..."

  dependency-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run dependency vulnerability scan
        uses: aquasecurity/trivy-action@master
        with:
          scan-type: "fs"
          scan-ref: "."

  api-spec-lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Lint OpenAPI specs
        run: npx @stoplight/spectral-cli lint api/openapi.yaml --ruleset .spectral.yaml

  dast:
    needs: [sast, dependency-check, api-spec-lint]
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/main'
    steps:
      - name: Deploy to staging
        run: ./deploy-staging.sh
      - name: Run DAST scan
        uses: zaproxy/action-full-scan@v0.10.0
        with:
          target: "https://staging-api.example.com"
          rules_file_name: "zap-rules.tsv"

// FinSecure 的资源授权框架
type ResourcePolicy struct {
    ResourceType string
    OwnerField   string           // 数据库中的所有者字段名
    AccessRules  []AccessRule
}

type AccessRule struct {
    Role       string   // 角色
    Actions    []string // 允许的操作
    Conditions []string // 附加条件
}

var policies = map[string]ResourcePolicy{
    "transaction": {
        ResourceType: "transaction",
        OwnerField:   "merchant_id",
        AccessRules: []AccessRule{
            {Role: "merchant", Actions: []string{"read"}, Conditions: []string{"own"}},
            {Role: "merchant_admin", Actions: []string{"read", "refund"}, Conditions: []string{"own"}},
            {Role: "platform_admin", Actions: []string{"read", "refund", "freeze"}, Conditions: nil},
        },
    },
    "settlement": {
        ResourceType: "settlement",
        OwnerField:   "merchant_id",
        AccessRules: []AccessRule{
            {Role: "merchant", Actions: []string{"read"}, Conditions: []string{"own"}},
            {Role: "finance", Actions: []string{"read", "approve"}, Conditions: nil},
        },
    },
}