Support lean MCP reports; move server & docs

[doomedraven]

Introduce a lightweight "lean" CAPE report flow and update MCP server location. Added mcp/filters.py (lean_search_filters) and mcp/init.py to expose configurable projection filters. Renamed web/mcp_server.py -> mcp/server.py and added get_lean_cape_report/_apply_lean_report plus lean flags to search_task, extended_search and task report handling to return reduced payloads for LLM/agent consumption. Adjusted docs (usage/mcp.rst) to reference the new module path and use Poetry (poetry run python mcp/server.py). Fixed perform_search usage in lib/cuckoo/common/web_utils.py to honor an optional projection argument and to compute ES _source fields from projection when provided. Updated web/apiv2/views.py to import and apply the lean projection in search and report endpoints.

[gemini-code-assist]

Summary of Changes

Hello @doomedraven, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the CAPE reporting system by introducing a 'lean' report format, which provides a concise subset of data optimized for AI models and agents. This change reduces payload size and processing overhead for specific use cases. Concurrently, the MCP server's codebase has been refactored for better modularity, and the documentation has been updated to reflect these structural and operational improvements. The core search functionality has also been made more flexible to support these new projection capabilities.

Highlights

• Lean CAPE Report Flow: Introduced a lightweight 'lean' CAPE report flow to generate reduced payloads, specifically designed for consumption by LLMs/agents.
• MCP Server Relocation: The MCP server script has been moved from 'web/mcp_server.py' to 'mcp/server.py' to improve module organization.
• Configurable Projection Filters: Added 'mcp/filters.py' to define and expose configurable projection filters, enabling customization of the data returned in lean reports.
• Documentation Updates: Updated documentation ('usage/mcp.rst') to reflect the new module path for the MCP server and to recommend using Poetry for execution.
• Flexible Search Projections: Modified the 'perform_search' utility function to accept an optional 'projection' argument, allowing dynamic control over returned fields in both MongoDB and Elasticsearch queries.
• API Integration of Lean Reports: Integrated the lean projection logic into the API's search and report endpoints, enabling clients to request reduced data payloads.

Changelog

• docs/book/src/usage/mcp.rst
  • Updated server execution commands to reflect the new 'mcp/server.py' path and Poetry usage.
• lib/cuckoo/common/web_utils.py
  • Modified 'perform_search' to accept an optional 'projection' argument for MongoDB aggregation and Elasticsearch _source fields.
• mcp/filters.py
  • Added a new file defining 'lean_search_filters' for specifying fields in reduced CAPE reports.
• mcp/server.py
  • Renamed from 'web/mcp_server.py' to 'mcp/server.py'.
  • Implemented 'get_lean_cape_report' to filter raw CAPE reports into a lean format.
  • Added '_apply_lean_report' to apply lean filtering to various result structures.
  • Introduced a 'lean' flag to 'search_task', 'extended_search', and 'get_task_report' functions to enable lean report generation.
• web/apiv2/views.py
  • Imported 'lean_search_filters' with fallback for compatibility.
  • Applied 'lean_search_filters' to 'ext_tasks_search' when a 'lean' flag is present in the request data.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces a 'lean' report feature, providing a lightweight version of CAPE reports for LLM agents, by adding a configurable projection filter and new functions. The MCP server has also been moved to its own mcp/ directory. However, the audit identified several high-severity security vulnerabilities: the perform_search function fails to enforce per-user access control, allowing users to access each other's analysis reports, and several MCP tools are vulnerable to API path traversal, which could allow an attacker to bypass tool restrictions and call arbitrary CAPE API endpoints. These critical issues should be addressed before merging. Additionally, while the changes are generally well-implemented, there are a couple of suggestions to improve code clarity and maintainability.