Components

The SigilAI platform is built from a set of logical components that collaborate to provide comprehensive security scanning services via the Model Context Protocol (MCP). This document outlines these major components and their functional roles within the overall architecture.

Conceptual Component Diagram

1. MCP Gateway

• Description: This is the primary entry point for all client interactions with the SigilAI platform. It acts as the public-facing interface that speaks the Model Context Protocol.

• Responsibilities:

  • Receiving and interpreting MCP messages from AI clients (e.g., LLMs, AI assistants).

  • Managing client sessions and secure communication channels (e.g., using SSE over HTTPS).

  • Authenticating and authorizing client requests (conceptual, actual implementation may vary).

  • Providing clients with information about available tools and their usage instructions.

  • Formatting responses and errors according to MCP specifications.

• Key Interactions:

  • Communicates directly with AI Clients.

  • Passes validated tool requests to the Tool Request Router.

  • Utilizes the Logging & Auditing Service for recording interactions.

2. Tool Request Router

• Description: An internal component responsible for directing incoming tool invocation requests to the appropriate analysis engine.

• Responsibilities:

  • Receiving validated tool requests from the MCP Gateway.

  • Identifying the target analysis engine based on the requested tool name.

  • Orchestrating the flow of data and control to the designated engine.

  • Aggregating results if a request involves multiple sub-tasks (conceptual).

• Key Interactions:

  • Receives requests from the MCP Gateway.

  • Delegates tasks to the URL Analysis Engine, File Analysis Engine, or Diagnostic Engine.

  • Uses Configuration Management for routing rules or tool-specific settings.

3. URL Analysis Engine

• Description: This engine is dedicated to processing requests for URL security scanning.

• Responsibilities:

  • Accepting URL analysis requests (containing the URL and any relevant context like user identifiers).

  • Implementing the logic for URL validation and normalization.

  • Coordinating with the URL Threat Intelligence Subsystem to perform the actual security assessment.

  • Compiling scan results, including safety status, identified threats, and warnings.

  • Formatting the results for transmission back through the MCP Gateway.

• Key Interactions:

  • Receives tasks from the Tool Request Router.

  • Utilizes the URL Threat Intelligence Subsystem.

  • May store or retrieve historical scan data via the Data Persistence Layer.

  • Logs activities through the Logging & Auditing Service.

3.1. URL Threat Intelligence Subsystem

• Description: A specialized subsystem that performs the detailed security checks on URLs.

• Responsibilities:

  • Querying various external threat feeds and internal security databases.

  • Analyzing URL structure, domain reputation, and content indicators.

  • Applying heuristics and rules to determine the risk level of a URL.

• Key Interactions:

  • Interfaces with external threat intelligence sources.

  • Provides detailed threat data to the URL Analysis Engine.

4. File Analysis Engine

• Description: This engine handles requests for source code file analysis.

• Responsibilities:

  • Accepting file analysis requests (typically including file path, content, and desired scan types).

  • Managing the secure transfer and temporary storage of file content for analysis.

  • Coordinating with the Code Vulnerability Assessment Subsystem.

  • Aggregating findings from different analysis tools (e.g., static analysis, dependency checking).

  • Formatting results, including identified vulnerabilities, severity levels, and remediation advice.

• Key Interactions:

  • Receives tasks from the Tool Request Router.

  • Utilizes the Code Vulnerability Assessment Subsystem.

  • May interact with the Data Persistence Layer for caching or result storage.

  • Logs activities via the Logging & Auditing Service.

4.1. Code Vulnerability Assessment Subsystem

• Description: Performs the in-depth analysis of source code.

• Responsibilities:

  • Executing various security analysis tools (e.g., SAST for static analysis, SCA for software composition analysis).

  • Interpreting raw outputs from these tools.

  • Normalizing and categorizing identified vulnerabilities (e.g., by CWE).

• Key Interactions:

  • Integrates with underlying security analysis tools (which could be commercial, open-source, or custom-built).

  • Provides structured vulnerability data to the File Analysis Engine.

5. Diagnostic Engine

• Description: Provides tools for testing the health and responsiveness of the SigilAI platform.

• Responsibilities:

  • Handling simple test requests (e.g., an "echo" tool).

  • Providing status information about the platform's components (conceptual).

  • Returning standardized diagnostic responses.

• Key Interactions:

  • Receives tasks from the Tool Request Router.

  • May query other components for status information.

6. Supporting Infrastructure Components

These components provide essential cross-cutting services to the core engines and gateway.

6.1. Configuration Management

• Description: Manages and provides configuration settings for all parts of the SigilAI platform.

• Responsibilities:

  • Storing and serving settings for tool behavior, external service endpoints, API keys, feature flags, etc.

  • Allowing for dynamic configuration updates where appropriate.

• Usage: Accessed by most other components to retrieve operational parameters.

6.2. Logging & Auditing Service

• Description: A centralized service for capturing logs, metrics, and audit trails.

• Responsibilities:

  • Collecting structured logs from all components.

  • Recording audit information for security and compliance purposes (e.g., tool invocations, access attempts).

  • Potentially integrating with external monitoring and alerting systems.

• Usage: Used by all operational components to record their activities and status.

6.3. Data Persistence Layer

• Description: Manages the storage and retrieval of data used or generated by the SigilAI platform.

• Responsibilities:

  • Storing historical scan results.

  • Caching frequently accessed data or intermediate results.

  • Managing user-specific data or preferences (if applicable).

  • Ensuring data integrity, availability, and security.

• Usage: Accessed by analysis engines for storing/retrieving scan data, and potentially by the MCP Gateway for session state if not purely stateless.

Component Interaction Philosophy

The SigilAI platform is designed with a clear separation of concerns. The MCP Gateway handles the external communication protocol, the Tool Request Router directs traffic, the Analysis Engines perform specialized tasks by leveraging their respective Subsystems, and the Supporting Infrastructure provides common services. This modular design allows for independent scaling, updating, and maintenance of different parts of the system, adhering to modern cloud architecture best practices.

---

Next: Security Model