id: microsoft_graph_files
name: Microsoft Graph Files
version: 1.0.0
description: "Microsoft Graph file management for O365 (OneDrive / SharePoint / Teams) — browse sites, drives and content, create folders, upload/replace/download files, manage site permissions, read SharePoint lists, and edit Excel worksheets. App-only authentication (client credentials)."
changelog: "1.0.0 — Initial release: SharePoint sites/drives/content browsing, folder creation, file delete/upload/replace/download (via URL or base64), site permission management (list/create/update/delete), SharePoint list reading (lists/items/get-item), and Excel worksheet editing (add-row/get-worksheet/update-cell). App-only client-credentials authentication."
category: productivity

# Per-instance configuration. Uses app-only (client credentials) authentication
# against Microsoft Graph. Register an Azure AD application with the required
# application permissions (e.g. Sites.ReadWrite.All, Files.ReadWrite.All) and admin
# consent, then provide the tenant id, client id and client secret.
config_schema:
  properties:
    host:
      type: string
      description: "Microsoft Graph base URL"
      default: https://graph.microsoft.com
    login_url:
      type: string
      description: "Azure AD login endpoint (change for national clouds, e.g. https://login.microsoftonline.us)"
      default: https://login.microsoftonline.com
    tenant_id:
      type: string
      description: "Azure AD tenant ID"
    client_id:
      type: string
      description: "Application (client) ID"
    client_secret:
      type: string
      description: "Client secret"
      x-soar-sensitive: true
    insecure:
      type: boolean
      description: "Trust any TLS certificate (not secure)"
      default: false
  required:
    - tenant_id
    - client_id
    - client_secret

# Documented for reference; the bundled scripts obtain a bearer token themselves
# via the client-credentials grant and set Authorization: Bearer <token>.
auth:
  - id: apikey
    type: api_key
    in: header
    name: Authorization
    value_template: "Bearer {{secret}}"
    secret_field: client_secret

commands:
  - id: test_connection
    name: msgraph-files-auth-test
    description: "Verify connectivity and credentials against Microsoft Graph (used by the Test button)."
    risk: read
    inputs_schema:
      properties: {}
      required: []
    outputs_schema: { properties: {} }

  # ── Sites / drives / content ──────────────────────────────────────────────
  - id: list_sharepoint_sites
    name: msgraph-list-sharepoint-sites
    description: "Search the tenant's SharePoint sites (requires Sites.Read.All)."
    risk: read
    inputs_schema:
      properties:
        keyword: { type: string, description: "Search keyword; defaults to all sites (*)" }
      required: []
    outputs_schema: { properties: {} }
  - id: list_drives_in_site
    name: msgraph-list-drives-in-site
    description: "List the document libraries (drives) of a site."
    risk: read
    inputs_schema:
      properties:
        site_id: { type: string, description: "Site ID (use msgraph-list-sharepoint-sites to find it)" }
        limit: { type: number, description: "Maximum results" }
        next_page_url: { type: string, description: "The @odata.nextLink URL for the next page" }
      required: []
    outputs_schema: { properties: {} }
  - id: list_drive_content
    name: msgraph-list-drive-content
    description: "List files and folders in a drive (object_type: drives/groups/sites/users)."
    risk: read
    inputs_schema:
      properties:
        object_type: { type: string, description: "drives, groups, sites or users" }
        object_type_id: { type: string, description: "The resource ID" }
        item_id: { type: string, description: "Folder item ID (default root)" }
        limit: { type: number, description: "Maximum results" }
        next_page_url: { type: string, description: "The @odata.nextLink URL for the next page" }
      required: [object_type, object_type_id]
    outputs_schema: { properties: {} }
  - id: create_new_folder
    name: msgraph-create-new-folder
    description: "Create a folder under a parent item in a drive."
    inputs_schema:
      properties:
        object_type: { type: string, description: "drives, groups, sites or users" }
        object_type_id: { type: string, description: "The resource ID" }
        parent_id: { type: string, description: "Parent item ID (root or a folder ID)" }
        folder_name: { type: string, description: "Name of the new folder" }
      required: [object_type, object_type_id, parent_id, folder_name]
    outputs_schema: { properties: {} }
  - id: delete_file
    name: msgraph-delete-file
    description: "Delete a drive item (file or folder) by its ID."
    inputs_schema:
      properties:
        object_type: { type: string, description: "drives, groups, sites or users" }
        object_type_id: { type: string, description: "The resource ID" }
        item_id: { type: string, description: "Item ID to delete" }
      required: [object_type, object_type_id, item_id]
    outputs_schema: { properties: {} }

  # ── File transfer (URL / base64) ──────────────────────────────────────────
  - id: download_file
    name: msgraph-download-file
    description: "Return a drive item's metadata and a pre-authenticated download URL. Set as_base64=true to also return the content base64-encoded (small files only)."
    risk: read
    inputs_schema:
      properties:
        object_type: { type: string, description: "drives, groups, sites or users" }
        object_type_id: { type: string, description: "The resource ID" }
        item_id: { type: string, description: "Item ID to download" }
        as_base64: { type: string, description: "Set true to also include base64 content (small files)" }
      required: [object_type, object_type_id, item_id]
    outputs_schema: { properties: {} }
  - id: upload_new_file
    name: msgraph-upload-new-file
    description: "Upload a new file into a folder. Provide the content via content_base64 or source_url."
    inputs_schema:
      properties:
        object_type: { type: string, description: "drives, groups, sites or users" }
        object_type_id: { type: string, description: "The resource ID" }
        parent_id: { type: string, description: "Parent folder ID" }
        file_name: { type: string, description: "Name for the uploaded file" }
        content_base64: { type: string, description: "File content, base64-encoded" }
        source_url: { type: string, description: "URL to fetch the file content from (alternative to content_base64)" }
      required: [object_type, object_type_id, parent_id, file_name]
    outputs_schema: { properties: {} }
  - id: replace_existing_file
    name: msgraph-replace-existing-file
    description: "Replace the content of an existing file. Provide the new content via content_base64 or source_url."
    inputs_schema:
      properties:
        object_type: { type: string, description: "drives, groups, sites or users" }
        object_type_id: { type: string, description: "The resource ID" }
        item_id: { type: string, description: "Item ID of the file to replace" }
        content_base64: { type: string, description: "New file content, base64-encoded" }
        source_url: { type: string, description: "URL to fetch the new content from (alternative to content_base64)" }
      required: [object_type, object_type_id, item_id]
    outputs_schema: { properties: {} }

  # ── Site permissions ──────────────────────────────────────────────────────
  - id: list_site_permissions
    name: msgraph-list-site-permissions
    description: "List application permissions on a site, or a single permission when permission_id is given. Provide site_id or site_name."
    risk: read
    inputs_schema:
      properties:
        site_id: { type: string, description: "Site ID (or provide site_name)" }
        site_name: { type: string, description: "Site name (resolved to an ID; or provide site_id)" }
        permission_id: { type: string, description: "A specific permission ID to retrieve" }
      required: []
    outputs_schema: { properties: {} }
  - id: create_site_permissions
    name: msgraph-create-site-permissions
    description: "Grant an application permission (read/write/owner) on a site."
    inputs_schema:
      properties:
        site_id: { type: string, description: "Site ID (or provide site_name)" }
        site_name: { type: string, description: "Site name (or provide site_id)" }
        role: { type: string, description: "read, write or owner" }
        app_id: { type: string, description: "Application (client) ID to grant" }
        display_name: { type: string, description: "Display name of the application" }
      required: [role, app_id, display_name]
    outputs_schema: { properties: {} }
  - id: update_site_permissions
    name: msgraph-update-site-permissions
    description: "Update the role of an existing site permission."
    inputs_schema:
      properties:
        site_id: { type: string, description: "Site ID (or provide site_name)" }
        site_name: { type: string, description: "Site name (or provide site_id)" }
        permission_id: { type: string, description: "Permission ID to update" }
        role: { type: string, description: "read, write or owner" }
      required: [permission_id, role]
    outputs_schema: { properties: {} }
  - id: delete_site_permissions
    name: msgraph-delete-site-permissions
    description: "Delete an application permission from a site."
    inputs_schema:
      properties:
        site_id: { type: string, description: "Site ID (or provide site_name)" }
        site_name: { type: string, description: "Site name (or provide site_id)" }
        permission_id: { type: string, description: "Permission ID to delete" }
      required: [permission_id]
    outputs_schema: { properties: {} }

  # ── SharePoint lists ──────────────────────────────────────────────────────
  - id: list_sharepoint_lists
    name: msgraph-list-sharepoint-lists
    description: "List the SharePoint lists of a site. Provide site_id or site_name."
    risk: read
    inputs_schema:
      properties:
        site_id: { type: string, description: "Site ID (or provide site_name)" }
        site_name: { type: string, description: "Site name (or provide site_id)" }
        limit: { type: number, description: "Maximum results" }
        next_page_url: { type: string, description: "The @odata.nextLink URL for the next page" }
      required: []
    outputs_schema: { properties: {} }
  - id: list_sharepoint_list_items
    name: msgraph-list-sharepoint-list-items
    description: "List items of a SharePoint list (with their fields). Provide list_id or list_name."
    risk: read
    inputs_schema:
      properties:
        site_id: { type: string, description: "Site ID (or provide site_name)" }
        site_name: { type: string, description: "Site name (or provide site_id)" }
        list_id: { type: string, description: "List ID (or provide list_name)" }
        list_name: { type: string, description: "List name (or provide list_id)" }
        limit: { type: number, description: "Maximum results" }
        filter: { type: string, description: "OData $filter expression" }
        orderby: { type: string, description: "OData $orderby expression" }
        fields_select: { type: string, description: "Comma-separated list of field columns to expand" }
        next_page_url: { type: string, description: "The @odata.nextLink URL for the next page" }
      required: []
    outputs_schema: { properties: {} }
  - id: get_sharepoint_list_item
    name: msgraph-get-sharepoint-list-item
    description: "Get a single SharePoint list item with its fields. Provide list_id or list_name."
    risk: read
    inputs_schema:
      properties:
        site_id: { type: string, description: "Site ID (or provide site_name)" }
        site_name: { type: string, description: "Site name (or provide site_id)" }
        list_id: { type: string, description: "List ID (or provide list_name)" }
        list_name: { type: string, description: "List name (or provide list_id)" }
        item_id: { type: string, description: "List item ID" }
      required: [item_id]
    outputs_schema: { properties: {} }

  # ── Excel ─────────────────────────────────────────────────────────────────
  - id: excel_add_row
    name: msgraph-excel-add-row
    description: "Append a row to an Excel worksheet. 'data' is a JSON object mapping column number (1-based) to value, e.g. {\"1\":\"foo\",\"2\":42}."
    inputs_schema:
      properties:
        object_type: { type: string, description: "drives, groups, sites or users" }
        object_type_id: { type: string, description: "The resource ID" }
        item_id: { type: string, description: "Workbook (xlsx) item ID" }
        worksheet_name: { type: string, description: "Worksheet name" }
        data: { type: object, description: "Object mapping 1-based column number to value" }
        start_row: { type: number, description: "Row to start appending from (default 1)" }
      required: [object_type_id, item_id, worksheet_name, data]
    outputs_schema: { properties: {} }
  - id: excel_get_worksheet
    name: msgraph-excel-get-worksheet
    description: "Read a range from an Excel worksheet (formatted text values)."
    risk: read
    inputs_schema:
      properties:
        object_type: { type: string, description: "drives, groups, sites or users" }
        object_type_id: { type: string, description: "The resource ID" }
        item_id: { type: string, description: "Workbook (xlsx) item ID" }
        worksheet_name: { type: string, description: "Worksheet name" }
        range: { type: string, description: "Range address, e.g. A1:Z500 (default A1:Z500)" }
      required: [object_type_id, item_id, worksheet_name]
    outputs_schema: { properties: {} }
  - id: excel_update_cell
    name: msgraph-excel-update-cell
    description: "Overwrite a single Excel cell. 'column' may be a number or 'Col_2'."
    inputs_schema:
      properties:
        object_type: { type: string, description: "drives, groups, sites or users" }
        object_type_id: { type: string, description: "The resource ID" }
        item_id: { type: string, description: "Workbook (xlsx) item ID" }
        worksheet_name: { type: string, description: "Worksheet name" }
        row_index: { type: number, description: "1-based row index" }
        column: { type: string, description: "Column number or 'Col_2'" }
        value: { type: string, description: "New cell value" }
      required: [object_type_id, item_id, worksheet_name, row_index, column, value]
    outputs_schema: { properties: {} }