Scope Optimization

Relevant source files

The following files were used as context for generating this wiki page:

• packages/shared/src/analyzers/scopeOptimizer.ts
• packages/shared/src/scanners/tests/dependencyScanner.test.ts
• packages/api/src/schemas/validation.ts
• README.md
• PHASE1_IMPLEMENTATION.md
• SYSTEM_EVALUATION.md

Scope Optimization is a core security feature of SecretForge AI designed to implement the principle of least privilege for API integrations. By analyzing the project's codebase and dependencies, the system determines the minimal set of permissions (scopes) required for specific services, thereby reducing the attack surface of provisioned API keys.

Sources: packages/shared/src/analyzers/scopeOptimizer.ts:1-7, README.md:15-20

Architecture and Core Logic

The Scope Optimization system operates by parsing source code across multiple languages to identify actual API endpoint usage. It matches identified calls against a known mapping of service methods to required permissions.

Optimization Workflow

The following diagram illustrates the flow from code analysis to the generation of a scope analysis result:

The system supports multiple languages and utilizes regex-based AST-like parsing to find specific service patterns for Stripe, AWS, OpenAI, Twilio, and SendGrid.
Sources: packages/shared/src/analyzers/scopeOptimizer.ts:114-307

Data Structures

The system relies on structured interfaces to represent the results of the analysis and the specific API calls detected.

Key Interfaces

Interface	Purpose
ScopeAnalysisResult	Contains recommended scopes, used endpoints, unused scopes, and confidence metrics for a single service.
APICall	Represents a single detected API call, including the service, method, required scope, and file location.
ProjectAnalysisResult	Aggregates service results and provides an overall optimization potential percentage.

Sources: packages/shared/src/analyzers/scopeOptimizer.ts:10-33, packages/shared/src/analyzers/scopeOptimizer.ts:286-293

Service Scope Mappings

The SCOPE_MAPPINGS object acts as the source of truth for translating code-level methods into security scopes.

const SCOPE_MAPPINGS: Record<string, Record<string, string[]>> = {
  stripe: {
    'customers.create': ['customers:write'],
    'customers.retrieve': ['customers:read'],
    // ...
  },
  aws: {
    's3.putObject': ['s3:PutObject'],
    's3.getObject': ['s3:GetObject'],
    // ...
  }
};

Sources: packages/shared/src/analyzers/scopeOptimizer.ts:39-86

Language-Specific Analyzers

The optimizer uses specialized extraction logic for different programming languages, identifying patterns unique to their respective SDKs.

JavaScript and TypeScript

Uses getServicePatterns to match common SDK patterns like stripe.customers.create or openai.chat.completions.create.
Sources: packages/shared/src/analyzers/scopeOptimizer.ts:127-147, packages/shared/src/analyzers/scopeOptimizer.ts:221-267

Python

Detects calls in requirements.txt or source code using regex for patterns like stripe.Customer.create or client.chat.completions.create.
Sources: packages/shared/src/analyzers/scopeOptimizer.ts:152-192, packages/shared/src/scanners/tests/dependencyScanner.test.ts:55-83

Go

Analyzes go.mod files and source code for patterns such as customer.New or s3Client.PutObject.
Sources: packages/shared/src/analyzers/scopeOptimizer.ts:197-235, packages/shared/src/scanners/tests/dependencyScanner.test.ts:88-105

Recommendation and Suggestion Logic

After extracting API calls, the system calculates a confidence score and generates actionable suggestions to improve security.

The confidence score is weighted by the number of API calls found, capped at 0.99. Specific suggestions are generated for Stripe (e.g., using read-only keys) and AWS (e.g., separating IAM roles for S3 operations).
Sources: packages/shared/src/analyzers/scopeOptimizer.ts:272-355

Integration with SecretForge

Scope Optimization is integrated into the broader SecretForge lifecycle through the CLI and API validation schemas.

• Dependency Scanning: The system initially identifies services via scanDependencies in files like package.json or Cargo.toml.
• Validation: The analyzeProjectSchema validates input for project paths and dependency records during API calls.
• Provisioning: The results inform the sf request command to provision keys with optimal scopes.

Sources: packages/shared/src/scanners/tests/dependencyScanner.test.ts:153-181, packages/api/src/schemas/validation.ts:40-45, README.md:145-150

Summary

Scope Optimization provides a programmatic way to enforce the principle of least privilege. By statically analyzing code and mapping usage to specific API permissions, SecretForge AI ensures that provisioned secrets are limited only to the functionality they actually require. This module significantly mitigates the risk associated with broad-access API keys and provides developers with clear, actionable security recommendations.

Sources: SYSTEM_EVALUATION.md:328-335, packages/shared/src/analyzers/scopeOptimizer.ts:357-393