> For the complete documentation index, see [llms.txt](https://help.nightfall.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.nightfall.ai/developer-api/nightfall_apis/nightfall-model-context-protocol-mcp-server/best-practices-security-investigation-workflows.md). # Best Practices - Security Investigation Workflows The following workflows represent best practices for common security tasks. These step-by-step patterns guide you through effective multi-tool investigations. #### Workflow 1: Incident Investigation **Purpose**: Conduct an end-to-end security incident investigation **Steps**: 1. **Identify the scope**: Search for related events using `search_violations`, `search_exfiltration_events`, or `search_posture_events` with your search criteria 2. **Gather details**: For each relevant result, use `get_violation`, `get_exfiltration_event`, or `get_posture_event` to get full context including affected assets, actors, and risk levels 3. **Review findings**: For violations, use `get_violation_findings` to see exactly what sensitive data was detected 4. **Check activity timeline**: Use the appropriate activity tools to understand what remediation has already been attempted 5. **Assess user behavior**: If an actor is identified, use `get_actor_activity` to check their recent activity across all event types 6. **Summarize and recommend**: Provide a structured incident summary with scope, affected assets, actors involved, risk assessment, and specific remediation actions **Example Conversation**: * "Investigate the incident involving repository finance-api" * "Show me the findings for violation abc-123" * "What has user been doing recently?" * "Summarize the risk and recommend next steps" #### Workflow 2: Violation Triage **Purpose**: Prioritize and triage active DLP violations for remediation **Steps**: 1. **Fetch active violations**: Use `search_violations` with query `state:ACTIVE` sorted by `RISK_DESC` to get highest-risk violations first 2. **Categorize by severity**: Group violations by `risk_label` (CRITICAL, HIGH, MEDIUM, LOW) and integration 3. **Get details for high-priority items**: For each CRITICAL and HIGH risk violation, use `get_violation` to understand context and available remediation actions 4. **Review sensitive findings**: For top violations, use `get_violation_findings` to understand what data was exposed 5. **Generate triage report**: Create a prioritized list with specific next steps using `take_action_on_violations` **Example Conversation**: * "Triage all active violations, prioritize by risk" * "Show me details for the top 5 high-risk violations" * "What are the findings for these violations?" * "Create a remediation plan for the critical violations" #### Workflow 3: Compliance Reporting **Purpose**: Generate security compliance summary across time periods **Steps**: 1. **Gather violation statistics**: Use `list_violations` with `createdAfter` timestamp for your reporting period 2. **Gather exfiltration statistics**: Use `list_exfiltration_events` with the same time range 3. **Gather posture statistics**: Use `list_posture_events` with the same time range 4. **Get details for key incidents**: Use the appropriate `get_*` tools for the most significant events 5. **Generate report**: Produce a structured report with executive summary, breakdowns by integration/severity, top incidents, trends, and recommendations **Example Conversation**: * "Generate a compliance report for the last 90 days" * "Break down violations by integration and severity" * "Show me the top 10 incidents with details" * "What trends are emerging in our security posture?" #### Workflow 4: User Risk Assessment **Purpose**: Assess security risk profile for a specific user **Steps**: 1. **Find violations**: Use `search_violations` with query `user_email:[email]` to find all DLP violations 2. **Find exfiltration events**: Use `search_exfiltration_events` with query `actor_email:[email]` 3. **Find posture events**: Use `search_posture_events` with query `actor_email:[email]` 4. **Get details on significant events**: For high-risk items, use the appropriate `get_*` tools 5. **Generate risk assessment**: Produce a user profile with statistics, risk score, timeline, behavioral patterns, and recommendations **Example Conversation**: * "Assess the risk profile for user " * "Show me all violations and events involving this user" * "What patterns emerge from their behavior?" * "Recommend appropriate actions based on their risk level" #### Workflow 5: Guided Remediation **Purpose**: Execute remediation actions on specific violations **Steps**: 1. **Review violation details**: Use `get_violation` to understand context and available actions 2. **Check findings**: Use `get_violation_findings` to see what data is at risk 3. **Verify appropriate action**: Confirm the remediation action matches the violation severity and context 4. **Execute remediation**: Use `take_action_on_violations` with appropriate action (RESOLVE, BLOCK, DELETE, etc.) 5. **Verify completion**: Check `get_violation_activity` to confirm the action was recorded **Example Conversation**: * "Show me details for violation xyz-789" * "What are the available remediation actions?" * "Resolve this violation and document the action" * "Confirm the remediation was successful" #### Multi-Step Tool Chaining * "Search for GitHub violations, get details on the top 3, and show me the sensitive findings" * "Find all violations by , check her recent activity, and assess her risk profile" * "List exfiltration events from last week, get details on any involving bulk downloads, and summarize the risk" * "Search for high-risk Slack violations, review their findings, and recommend remediation actions" #### Multi-Tool Investigation Patterns The most effective investigations use multiple tools in sequence. Follow these patterns: **Basic Investigation Pattern**: 1. Search → Get Details → Analyze → Recommend **Deep Investigation Pattern**: 1. Search → Get Details → Get Findings → Check Activity → Assess Actor → Recommend **Remediation Pattern**: 1. Search → Get Details → Verify Context → Take Action → Confirm When asking complex questions, the AI will automatically chain tools in the optimal order. You can also explicitly request multi-step workflows: "Search for high-risk violations, review the top 5, and create a remediation plan." #### Effective Communication with AI * Be specific about time ranges: "last 7 days" is clearer than "recently" * Use exact usernames or email addresses when investigating specific actors * Ask follow-up questions to drill deeper: "Show me the findings" after reviewing a violation * Request summaries for complex data: "Summarize these violations by severity" * Clarify formatting preferences: "Show as a table" or "Give me a bullet list" * Chain multiple steps in one request: "Search for violations, get details on the top 3, and show findings" is more efficient than three separate questions * Use date ranges to limit result sets when investigating recent incidents * Ask for pagination when dealing with large result sets to avoid overwhelming responses * Combine filters naturally: "high-risk GitHub violations from last week" is more efficient than multiple separate queries #### Security * Store API keys in secure credential managers, never in code or configuration files committed to version control * Rotate API keys quarterly or immediately if compromise is suspected * Use dedicated API keys for each integration rather than sharing across systems * Review API key permissions regularly and follow least-privilege principles * Enable audit logging in your AI client to track MCP queries for compliance #### Effective Communication with AI * Be specific about time ranges: "last 7 days" is clearer than "recently" * Use exact usernames or email addresses when investigating specific actors * Ask follow-up questions to drill deeper: "Show me the findings" after reviewing a violation * Request summaries for complex data: "Summarize these violations by severity" * Clarify formatting preferences: "Show as a table" or "Give me a bullet list" #### Workflow Integration * Set up dedicated Slack/Teams channels for security alerts and use MCP to investigate directly from your collaboration tool * Create saved prompts for common investigations to maintain consistency across your security team * Document investigation procedures that leverage MCP for faster onboarding of new analysts * Use MCP in conjunction with the Nightfall console for comprehensive security operations --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://help.nightfall.ai/developer-api/nightfall_apis/nightfall-model-context-protocol-mcp-server/best-practices-security-investigation-workflows.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.