Feat/903 soroban entrypoint analyzer

[T-kesh]

Implement Soroban Contract Entry-Point Analyzer (#903)

Summary

This pull request implements the Soroban Contract Entry-Point Analyzer along with dedicated detection rules and unit tests. Entry points determine how users and external contracts interact with contract logic. This analyzer performs comprehensive static analysis of public and externally accessible Soroban contract entry points to extract function signatures and parameters, trace authorization paths, and monitor storage accesses and external/cross-contract invocations.

What Changed

1. Soroban Entry-Point Analyzer (packages/analyzers/soroban/entrypoints/)

• types.ts: Comprehensive data structures for entry points, parameters (isEnv, isAddress, isAuthParam, isCollection, isMutable, isReference, docComment, isUnused), authorization checks (require_auth, require_auth_for_args, auth.authenticate, invoker), storage access (instance, persistent, temporary, reads/writes, keys, TTL extensions), external calls (invoke_contract, TokenClient, typed clients, balance queries, token transfers/mints/burns), and aggregate metrics.
• entry-point-analyzer.ts:
  • Discovers entry points across #[contractimpl] blocks, impl Trait for Contract implementations, impl Contract blocks, pub trait declarations, and standalone pub fn functions.
  • Accurately classifies visibility (public, constructor, internal, private) and identifies constructors/initializers (init, new, initialize).
  • Parses multi-line and typed function signatures, parameters, and attached Rust doc comments.
  • Traces authorization paths, maps authorized parameters, and identifies unprotected state-mutating entry points.
  • Monitors storage operations and tracks access within loops or branches.
  • Tracks cross-contract invocations and token client interactions.
  • Computes composite risk scores (critical, high, medium, low, safe) and generates executive summaries.
• index.ts: Re-exports types and analyzer while preserving backward compatibility with the existing profile analyzer module.
• __tests__/entry-point-analyzer.spec.ts: 18 unit tests covering all analyzer requirements and edge cases.

2. Soroban Entry-Point Rules (packages/rules/soroban/entrypoints/)

• types.ts: Defines finding types, severity classifications, and report models.
• entry-point-rule.ts: Provides rule engine validators:
  • soroban-unprotected-entry-point (Critical): Public state-mutating entry point lacking caller authorization.
  • soroban-entry-point-call-in-loop (High): Cross-contract or token calls executed inside loop constructs.
  • soroban-entry-point-storage-in-loop (High): Storage writes performed inside loop constructs.
  • soroban-entry-point-auth-in-loop (Medium): Authorization checks placed inside loops.
  • soroban-entry-point-redundant-auth (Low): Redundant multi-authorization checks on the same address.
  • soroban-entry-point-unused-parameter (Low): Unreferenced parameters in public entry points.
  • Specific validator helpers: validateEntryPointAuthorization, validateEntryPointExternalCalls, and validateEntryPointStorage.
• index.ts: Exports rule functions and types.
• __tests__/entry-point-rule.spec.ts: 7 unit tests validating clean and vulnerable contracts.

3. Package Integration

• packages/rules/soroban/src/entrypoints/index.ts: Internal package export wrapper.
• packages/rules/soroban/src/index.ts: Re-exports entrypoints module for global rule engine consumers.

Requirements & Acceptance Criteria Checklist

• Entry-Point Analyzer implemented: SorobanEntryPointAnalyzer and analyzeEntryPoints function created.
• Public functions identified: Correctly detects #[contractimpl] methods, trait implementations, pub fn, and constructors while distinguishing internal helper functions.
• Parameters extracted: Full parameter parsing including types, isEnv, isAddress, collections (Vec, Map, etc.), mutability, references, and doc comments.
• Authorization paths tracked: Tracks require_auth, require_auth_for_args, auth in loops, redundant auth, parameter authorization mapping, and flags unprotected state mutations.
• Storage tracked: Tracks instance/persistent/temporary reads, writes, TTL extensions, unique keys, and loop storage access.
• External calls tracked: Tracks env.invoke_contract, TokenClient, typed clients, transfers, mint/burn, balance queries, and calls in loops.
• Unit tests added: 25 test cases across analyzer and rule test suites.

Verification

=== RUNNING SOROBAN ENTRY-POINT ANALYZER SPEC ===
📦 SorobanEntryPointAnalyzer (#903)
  ✓ identifies public entry points, constructors, and internal functions
  ✓ identifies entry points from trait implementations
  ✓ identifies standalone pub fn functions
  ✓ extracts parameters with types, flags, and doc comments
  ✓ extracts collection parameters and return types
  ✓ extracts mutable and reference parameters correctly
  ✓ tracks require_auth and maps authorized parameters
  ✓ tracks require_auth_for_args and extracts arguments
  ✓ detects unprotected state-mutating entry points
  ✓ detects authorization check inside loops
  ✓ detects redundant authorization checks
  ✓ tracks instance storage reads and writes with keys
  ✓ detects storage operations inside loops
  ✓ tracks TTL extensions on instance and persistent storage
  ✓ tracks cross-contract invocations
  ✓ tracks TokenClient and typed Client calls
  ✓ detects external calls inside loops
  ✓ generates accurate metrics and executive summary
  ✓ handles empty contract source gracefully

=== RUNNING SOROBAN ENTRY-POINT RULES SPEC ===
📦 Soroban Entry-Point Rules (#903)
  ✓ returns 0 critical/high findings for clean contracts
  ✓ detects all entry point issue categories in vulnerable contract
  ✓ validateEntryPointAuthorization returns only authorization findings
  ✓ validateEntryPointExternalCalls returns only external call findings
  ✓ validateEntryPointStorage returns only storage findings
  ✓ behaves identically to detectEntryPointIssues

SUMMARY: 25 passed, 0 failed

All 10 pre-existing entry-point profiler tests continue to pass.

Closes #903

[drips-wave]

@T-kesh Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

[mijinummi]

Hi @T-kesh kindly fix the conflict

[T-kesh]

Hi @T-kesh kindly fix the conflict

I will get on that right away