sec-cluster

sec-cluster: Security Code Clustering

Dataflow-based code clustering for security assessments. Groups (Endpoint, Sink) paths by shared review strategy, enabling representative-sample review instead of exhaustive per-path analysis.

Core Principle

A cluster does not guarantee identical results. A cluster provides the possibility of applying the same review strategy.

Therefore the operating procedure is: verify clusters while using them, not trust them blindly.

When to Use

• Codebase has 50+ endpoints with repetitive security patterns
• Multiple modules share similar sanitization/validation gaps
• Need to scope a manual review efficiently after initial SAST/SCA
• Architecture review requests cluster-to-scenario mapping

Inputs

• Source repository (buildable preferred)
• Existing sec-audit-static findings (optional, accelerates Phase 1)
• Architecture review scenarios (optional, for cross-reference)

Workflow

Phase 0: Read References

1. Read references/clustering_strategy_v4.md for the full strategy.
2. Review templates/ for output format examples.

Phase 1: Scope and Exclusion

Determine clustering applicability per the v4 strategy:

Include (requires dataflow analysis):

Check Item	Clustering Reason
XSS	Sink context (HTML, JS, attribute) determines vulnerability
Data protection	Masking/encryption/exposure varies by flow
SSRF / path traversal / template injection	Input propagation path analysis required
Auth/authz (conditional)	Per-endpoint authorization application differs (v4 section 3.3)

Exclude (static pattern matching sufficient):

• Single-rule detectable patterns (e.g., Runtime.exec, ProcessBuilder)
• Uniformly handled by a common module
• Batch/cron paths without inbound HTTP endpoints
• Hardcoded secrets/keys (Gitleaks/Semgrep regex)

Auth/Authz Re-definition (v4 section 3.3):

Auth is not "does a common module exist" but "is it applied per-endpoint." Include in clustering when endpoint-level authorization varies.

Phase 2: Automated Detection (Semgrep Sweep)

1. Adapt semgrep rule templates from templates/semgrep-rules/ to the target codebase:
   • Replace project-specific identifiers with target-appropriate patterns
   • Adjust metavariable-regex for domain-specific field names
   • Add/remove rules based on Phase 1 scope decisions
2. Run sweep using templates/sweep.sh (adapt module list):

   ./sweep.sh              # all modules, human output
   ./sweep.sh --json       # JSON output
   ./sweep.sh <module>     # single module
   

3. Record match counts per cluster per module.

Phase 3: Endpoint Enumeration (C1 Auth Cluster)

For the auth/authz cluster (typically the largest):

1. Enumerate all @RequestMapping/@GetMapping/@PostMapping endpoints
2. For each controller, check:
   • @PreAuthorize, @Secured, SecurityFilterChain presence
   • WebConfig/addInterceptors() auth interceptor registration
   • Service-layer signature/HMAC/token verification
3. Record: module, controller, endpoint count, auth mechanism (or "none")
4. Use templates/auth_enum.sh as a starting point (adapt grep patterns).

Phase 4: Cluster Definition

Define clusters using the (Endpoint, Sink) unit. For each cluster, document:

Element	Description
Source	User input / external data entry point
Transformation	Processing logic
Validation/Sanitization	Filtering, encoding presence
Sink	Final output point (DB, HTTP response, file, external call)
Context	Auth state, data sensitivity, trust boundary

Typical cluster categories:

• C1: Endpoint-level auth/authz gaps (conditional)
• C2: Hardcoded shared-secret / manual-processing patterns
• C3: SSL/Hostname verification bypass (unsafe consumption)
• C4: Sensitive data logging (identifiers, credentials, full request/response)
• C5: Unsafe deserialization (XML/XStream/XXE without hardening)

Adjust cluster definitions to the target codebase. Not all categories apply to every project.

Phase 5: Representative Sample Review (Bootstrapping)

Per v4 section 7.5:

Stage	Criteria	Sampling
Stage 1 (initial)	New cluster	50%+ manual review, measure consistency
Stage 2 (stabilization)	Consistency >= 80%	Reduce to 30% sampling
Stage 3 (operational)	Miss rate < 5% for 2 consecutive cycles	Representative sample only
Re-verification trigger	Major code change, new framework, missed vuln	Reset to Stage 1

For each sample, fill the review checklist (see templates/REVIEW_CHECKLIST.md.tmpl):

• Check auth mechanisms, sanitizers, sink protections
• Mark [X] (vulnerable), [N] (not vulnerable), or [partial]
• Record cross-cluster interactions (e.g., C1 x C5 = auth gap + deserialization)

Phase 6: Output Generation

Produce these artifacts in the target's architecture-review/ or assessment output directory:

1. CLUSTERS.md — Full cluster inventory with:

   • Scope and exclusions
   • Per-cluster definition (feature table, endpoint-sink enumeration, representative samples)
   • Phase 2 match counts (actual vs. estimated)
   • Cross-cluster interaction matrix
   • Off-scope findings discovered during clustering
   • Bootstrapping guide with consistency metrics

2. semgrep-rules/ — Adapted rules with results/SUMMARY.md

3. semgrep-rules/results/REVIEW_CHECKLIST.md — Completed review with:

   • Per-sample verdicts
   • Consistency rate per cluster
   • Bootstrapping stage judgment

Failure Conditions

Clustering is ineffective when:

Condition	Reason
Reflection / dynamic dispatch	Static analysis cannot trace actual flow
AOP / proxy-based flow	Runtime-determined security processing
Framework internal hidden flow	Dataflow breaks inside framework
Runtime config-dependent sanitizer	Same code, different behavior by config
Template engine internal processing	Cannot trace internal escaping

Fallback: Tag failed paths in Phase 1, manage separately, review manually prioritized by: external input proximity > auth bypass potential > rest.

Outputs

Artifact	Description	Consumed By
CLUSTERS.md	Cluster definitions, measurements, cross-references	sec-audit-static, security-architecture-review
semgrep-rules/*.yaml	Codebase-adapted detection rules	sec-audit-static re-runs
semgrep-rules/results/SUMMARY.md	Detection statistics	CLUSTERS.md, architecture review
semgrep-rules/results/REVIEW_CHECKLIST.md	Sample review verdicts and consistency	Architecture review, next audit cycle

Handoff to Architecture Review

Provide:

• Cluster-to-scenario mapping (e.g., C1 -> S1,S2,S4)
• Cross-cluster attack chains (e.g., C1 x C5 = auth gap + unsafe deserialization)
• Consistency metrics per cluster (bootstrapping stage)
• Off-scope findings with severity assessment

Evaluation Metrics (v4 Section 7)

Metric	Definition	Formula
Intra-cluster consistency	Same-verdict rate within cluster	(matching samples) / (reviewed samples)
Review efficiency	Time saved vs. exhaustive review	1 - (clustered time) / (unclustered time)
Sample miss rate	Vulnerabilities missed by representative sampling	(mismatched samples) / (additional samples)
Reviewer agreement	Cross-reviewer verdict consistency	Cohen's Kappa or simple agreement rate

Resources

• references/clustering_strategy_v4.md — Full v4 strategy document
• templates/semgrep-rules/ — Starter rule templates (5 categories)
• templates/sweep.sh — Module sweep runner
• templates/auth_enum.sh — Auth mechanism enumeration helper
• templates/CLUSTERS.md.tmpl — Cluster document template
• templates/REVIEW_CHECKLIST.md.tmpl — Review checklist template

Related Reading

• Structure Builders Will Outlast Vulnerability Finders — Systematic structure over ad-hoc finding