AgentDock Core Documentation

Initial Security Audit

This document summarizes the findings of an initial security review performed on the AgentDock codebase (focusing on agentdock-core and the open source client layer). It identifies potential vulnerabilities, analyzes risks, and tracks actions taken or recommended.

Key:

  • ✅ = Issue Addressed / Mitigated / Low Risk / Current State OK
  • ⚠️ = Action Required / Future Enhancement / High Priority

1. API Key Handling and Security:

  • Issue: Flexible API key management using environment variables and client-side localStorage (via SecureStorage).
  • Analysis: Offers flexibility suitable for the OS client. SecureStorage uses AES-GCM encryption and HMAC, but is vulnerable to XSS attacks as encryption keys are also stored in localStorage. Environment variables depend on secure deployment configuration. Keys are masked in logs.
  • Status: ✅ (Current implementation acceptable for OS client, risks noted)
  • Recommendation: ✅ Document SecureStorage XSS risk clearly. Emphasize env vars/BYOK for production. (Documentation updated).

2. Input Validation:

  • Issue: Ensuring comprehensive validation of all external inputs. Potential ReDoS risk in specific regex.
  • Analysis: Zod validation is used effectively in key areas. ReDoS risk in extractArxivId assessed as low due to prior Zod validation.
  • Status: ✅ (Current validation good, risk low)
  • Recommendation: ⚠️ Perform focused audit of remaining API inputs and JSON.parse points for completeness.

3. Error Handling and Information Disclosure:

  • Issue: Potential for verbose errors leaking internal details in production.
  • Analysis: The parseProviderError and normalizeError system correctly sanitizes errors and conditionally excludes details in production based on NODE_ENV.
  • Status: ✅ (Mechanism prevents info disclosure in production)
  • Recommendation: None (Ensure NODE_ENV is set correctly in deployments).

4. Authentication and Authorization:

  • Issue: Lack of explicit user authentication in agentdock-core. Security relies on API key protection.
  • Analysis: User auth is intentionally out-of-scope for agentdock-core. API key security relies on environment variables and SecureStorage (with its XSS risk).
  • Status: ✅ (Acknowledged scope, risk noted)
  • Recommendation: ✅ Document SecureStorage XSS risk and secure key management practices. (Documentation updated).

5. Data Handling and Storage:

  • Issue: Default MemoryStorageProvider is non-persistent.
  • Analysis: The framework defaults to non-persistent memory storage. Persistent options (RedisStorageProvider, VercelKVProvider) are implemented and must be explicitly configured via environment variables for production.
  • Status: ✅ (Persistent options exist, but configuration required)
  • Recommendation: ⚠️ Emphasize critical need for configuring Redis/Vercel KV in production documentation.

6. Code Structure and Common Errors:

  • Issue: Potential inconsistencies in error handling patterns and lack of general retry mechanisms.
  • Analysis: agentdock-core uses standardized AgentError. The open source client layer uses console.error more variably. General retry mechanism for transient errors is missing.
  • Status: ⚠️ (Inconsistencies and lack of retries identified)
  • Recommendation: ⚠️ Standardize logging/API error responses in client layer. Implement general retry mechanism (e.g., exponential backoff) as future enhancement.

7. Dependencies:

  • Issue: Vulnerabilities in dependencies.
  • Analysis: pnpm audit initially found 1 critical (next) and 2 moderate (undici, esbuild) vulnerabilities.
  • Status: ✅ (Vulnerabilities resolved via updates and overrides)
  • Recommendation: ✅ Perform regular dependency audits (pnpm audit) and updates.

8. Browser Security (XSS):

  • Issue: Use of rehype-raw in Markdown components allows potential XSS.
  • Analysis: Risk medium/high (LLM output, community docs).
  • Status: ✅ (Resolved by switching to rehype-sanitize, testing confirmed OK)
  • Recommendation: Consider future sandboxing for Mermaid diagrams.

9. Rate Limiting and Resource Management:

  • Issue: Lack of server-side API rate limiting and basic tool throttling.
  • Analysis: No server-side rate limiting implemented (DoS risk). Tool throttling is basic (sleep()). Internal plan exists for implementation.
  • Status: ⚠️ (Rate limiting not implemented)
  • Recommendation: ⚠️ Implement server-side rate limiting (e.g., using @upstash/ratelimit with KV store) as planned internally (high priority). ⚠️ Improve tool throttling beyond sleep().

10. NoSQL Injection (if applicable):

  • Issue: Potential future risk if NoSQL databases are added.
  • Analysis: Not currently applicable to KV stores.
  • Status: ✅ (Not applicable currently)
  • Recommendation: Note for future database integrations.

General Recommendations

  • ⚠️ Conduct regular security audits and penetration testing.
  • ⚠️ Maintain clear security best practices documentation for users and contributors.
  • ⚠️ Consider dedicated security code reviews before major releases.

Next Actions (Based on Audit)

  1. Documentation Updates:
    • ✅ Clearly document the XSS risk associated with SecureStorage (client-side API key storage) and recommend secure alternatives (env vars, BYOK). (Updated in docs/oss-client/nextjs-implementation.md and linked from docs/roadmap/storage-abstraction.md). (See Issue 1, 4)
    • ⚠️ Emphasize the critical need for users to configure a persistent storage provider (Redis/Vercel KV) for production, detailing environment variable setup. (See Issue 5)
    • ⚠️ Create/expand security best practices documentation covering key management, input validation principles, etc. (See General Recs)
  2. High Priority Implementation:
    • ⚠️ Implement server-side API rate limiting based on the internal plan (using @upstash/ratelimit or similar). (See Issue 9)
  3. Future Enhancements / Code Improvements:
    • ⚠️ Perform a focused audit of API inputs and JSON.parse points to ensure comprehensive validation coverage. (See Issue 2)
    • ⚠️ Standardize logging (using structured logger) and API error responses in the open source client layer. (See Issue 6)
    • ⚠️ Implement a general retry mechanism (e.g., exponential backoff) for external API calls (LLMs, tools). (See Issue 6)
    • ⚠️ Improve tool throttling beyond simple sleep() delays. (See Issue 9)
    • ⚠️ Consider sandboxing for Mermaid diagrams for future enhancement. (See Issue 8)
  4. Process Improvements:
    • ✅ Establish a process for regular dependency audits (pnpm audit). (Implicitly done by performing this audit, recommend formalizing)
    • ⚠️ Incorporate regular security reviews/audits into the development lifecycle. (See General Recs)

This audit provides a snapshot. Ongoing vigilance and security practices are crucial.