microsoft/PAX copilotinteractions-v1.0.0

Copilot Interactions Content Audit Log Processor v1.0.0

Repository: microsoft/PAX

Tag: copilotinteractions-v1.0.0

Published: 2025-11-20T13:07:32Z

Prerelease: no

Release notes:

Release Notes: v1.0.0

Release Information

• Version: 1.0.0
• Release Date: 2025-11-19
• Released By: Brian Middendorf (@microsoft)
• Previous Version: N/A (Initial Release)

---

⚠️ Important Usage & Compliance Disclaimer

Please note:

While this tool helps customers better understand their Microsoft 365 Copilot interaction data, Microsoft has no visibility into the data that customers input into this script/tool, nor does Microsoft have any control over how customers will use this script/tool in their environment.

Customers are solely responsible for securing, storing, and processing all exported data in compliance with their organization's policies and all applicable laws and regulations, including but not limited to data privacy, security, and regulatory requirements (e.g., GDPR, HIPAA, PCI DSS, and data residency obligations).

This script outputs highly sensitive Copilot interaction content, including user prompts and Copilot responses, which may contain confidential, regulated, or personally identifiable information (PII). By using this script, you acknowledge and agree:

• You must implement appropriate safeguards, including encryption, access controls, and data classification, before running or sharing outputs generated by this script.
• Do not run this script on shared or unmanaged devices. Ensure that only authorized personnel have access to the exported data.
• Apply data loss prevention (DLP) policies and sensitive information detection where possible.

Microsoft provides this script "as-is" without warranties of any kind and disclaims all liability for any loss, breach, or misuse of data arising from or related to your use of this script. Microsoft does not provide support for custom modifications or downstream uses of this script. All operational risk and compliance obligations rest with you.

✅ Additional Guidance

Consult Your Compliance Team Before using this script, consult your organization's legal and compliance teams to confirm that your planned usage aligns with internal policies and external regulatory requirements.

Retention & eDiscovery Obligations Data exported by this script may fall under retention, legal hold, or eDiscovery obligations. Ensure that your organization's compliance policies are applied to any exported files.

🔐 Security Best Practices Checklist

• ☑ Rotate credentials regularly (client secrets or certificates) and never hard-code secrets in scripts.
• ☑ Run only in secure environments (managed devices, trusted networks).
• ☑ Apply encryption at rest and in transit for all exported files.
• ☑ Restrict access to exported data to authorized personnel only.
• ☑ Enable DLP and sensitivity labels to prevent accidental sharing.
• ☑ Validate storage location (e.g., secure SharePoint or encrypted file share).
• ☑ Review logs and outputs for sensitive content before distribution.
• ☑ Apply retention and deletion policies to exported data in line with compliance requirements.

🧪 Experimental Script Notice

This is an experimental script. On occasion, you may notice small deviations from metrics in the official Microsoft 365 Copilot Dashboards. We will continue to iterate based on your feedback. Currently available in English only.

---

Overview

Version 1.0.0 is the initial release of the Copilot Interactions Content Audit Log Processor, designed to export and analyze detailed Microsoft 365 Copilot interaction content including user prompts and AI responses. This script leverages the Microsoft Graph API `aiInteraction` resource type, providing organizations with comprehensive visibility into Copilot usage patterns, prompt analysis, and content security.

Key Features

1. Content-Rich Copilot Interaction Export

• Access detailed Microsoft 365 Copilot interaction data via Microsoft Graph API
• Includes user prompts (Body field when -IncludeBody used)
• Captures AI responses, interaction metadata, and timestamp information
• Supports interaction types: userPrompt and aiResponse

2. Flexible Export Options

• CSV Export: Default output format with UTF-8 encoding
• Excel Workbooks: Single-sheet exports via -ExportWorkbook parameter
• Auto-formatted columns with frozen headers
• Timestamp-based file naming for easy identification
• Optional user enrichment data included when -IncludeUserInfo used
• Append Mode: -AppendFile adds new data to existing export files for cumulative datasets
• Works with both CSV and Excel formats
• Validates schema compatibility before appending
• Enables building consolidated exports over time
• User Enrichment: Optional -IncludeUserInfo for Entra ID user profile data and MAC licensing
• User-Only Mode: -OnlyUserInfo exports only Entra ID user directory and MAC licensing (no interaction data) for fast license snapshots

3. Incremental Export with Watermarks (`-UseWatermark`)

• Efficient incremental exports: Track last processed interaction timestamp per user
• Automatic state management: Watermark files store last export position for each user
• Rolling audit trails: Build cumulative datasets with daily/scheduled updates
• Early-exit optimization: Stops pagination when reaching previously seen timestamps
• File-based persistence: Simple JSON watermark files for easy monitoring and management

4. Flexible Date Range Controls

• Custom date ranges: -StartDate and -EndDate parameters for historical analysis
• Days-back calculation: -DaysBack parameter for relative date ranges (default: 180 days)
• Timezone handling: Input dates interpreted as local timezone, all output timestamps exported in UTC
• Cross-timezone consistency: UTC output enables consistent analysis across global organizations

5. Enterprise-Grade Authentication

• App-only authentication: Uses client credentials flow (OAuth 2.0) with Microsoft Entra ID app registration
• Service principal execution: Requires -TenantId, -ClientId, -ClientSecret for unattended operation
• Environment variable support: Credentials can be set via $env:GRAPH_TENANT_ID, $env:GRAPH_CLIENT_ID, $env:GRAPH_CLIENT_SECRET
• No interactive authentication: Designed for scheduled/automated execution without user...