InsightConnect Marketplace

Microsoft Office365 Email Security

Back to Marketplace

Microsoft Office365 Email Security

v2.2.0

A collection of utilities related to Office 365 email security tasks

Tags: Office365, Microsoft, Administration, Spam, Phishing, Remediation, Email


Actions
  • Block Sender Transport Rule
  • Email Compliance Search
  • Email Compliance Purge
  • Email Compliance Search and Purge
  • Message Trace

Microsoft Office365 Email Security

About

Microsoft Office365 is a complete, intelligent solution, powered by Office 365 and Windows 10, allowing you to empower your team, safeguard your business, and simplify IT management.

This plugin adds utilities to help administrators manage their Office 365 instances.

Actions

Block Sender Transport Rule

This action is used to add a domain or email address to a blocking transport rule in Exchange Admin Center.

In the Office 365 cloud, transport rules are limited to 8k of data or roughly 8100 characters. This is roughly 400 email address. If a new email address is added that would break that limit, the oldest email address(es) in the current rule will be deleted to make room.

Input

Name Type Default Required Description Enum
domain_or_email_to_block string None True Domain or email address to block None
transport_rule_name string InsightConnect Block List True Transport rule name None

Output

Name Type Required Description
result string True Result

Example output:

{
    "result": "Success"
}

This action is used to create a compliance search for a provided email.

Input

Name Type Default Required Description Enum
compliance_search_name string None True Name of compliance search None
content_match_query string None True This parameter uses a text search string or a query that's formatted by using the Keyword Query Language (KQL). For more information about KQL, see Keyword Query Language syntax reference (https://go.microsoft.com/fwlink/p/?linkid=269603) None
query_timeout integer 60 False Query timeout in minutes None
users []string True Email address of all affected users

Output

Name Type Required Description
affected_users integer True Number of affected users
emails_found integer True Emails found that matched

Example output:

{
  "affected_users": 1,
  "emails_found": 4,
  "users": ["userA@company.com", "userB@company.com"]
}

Email Compliance Purge

This action is used to purge a provided email.

Input

Name Type Default Required Description Enum
compliance_search_name string None True Name of compliance search None
query_timeout integer 60 False Query timeout in minutes None

Output

Name Type Required Description
success boolean True Success

Example output:

{
    "result": "Success"
}

Email Compliance Search and Purge

This action is used to execute a search and purge for a provided email.

Input

Name Type Default Required Description Enum
compliance_search_name string None True Name of compliance search None
content_match_query string None True This parameter uses a text search string or a query that's formatted by using the Keyword Query Language (KQL). For more information about KQL, see Keyword Query Language syntax reference (https://go.microsoft.com/fwlink/p/?linkid=269603) None
delete_items boolean False False The script only executes the delete action if this parameter is true None
query_timeout integer 60 False Query timeout in minutes None

Output

Name Type Required Description
success boolean True Success

Example output:

{
    "result": "Success"
}

Message Trace

This action is used to run a message trace.

Input

Name Type Default Required Description Enum
Sender_address string None True Sender address None
end_date string None True End date in format MM/DD/YYYY e.g. 09/27/2019 None
start_date string None True Start date in format MM/DD/YYYY e.g. 09/27/2019 None

Output

Name Type Required Description
message_traces []message_trace True Success

Example output:

[
  {
    "PSComputerName": "outlook.office365.com",
    "RunspaceId": "eb0ea814-0c3d-45eb-a189-f41118e8582d",
    "PSShowComputerName": false,
    "Organization": "things.com",
    "MessageId": "<***********************.namprd12.prod.outlook.com>",
    "Received": "2019-09-24T14:18:57.4237718",
    "SenderAddress": "a_compny@things.com",
    "RecipientAddress": "a_compny@things.com",
    "Subject": "Android Update 5.2.1",
    "Status": "Delivered",
    "ToIP": null,
    "FromIP": "216.93.244.203",
    "Size": 15846,
    "MessageTraceId": "d7b67cd8-a69c-46e5-8816-08d740fa2349",
    "StartDate": "2019-09-20T00:00:00",
    "EndDate": "2019-09-25T00:00:00",
    "Index": 0
  }
]

Triggers

This plugin does not contain any triggers.

Connection

The connection configuration accepts the following parameters:

Name Type Default Required Description Enum
credentials credential_username_password None True Username and password None
office_365_url string https://ps.compliance.protection.outlook.com/powershell-liveid/ False This parameter sets the location of the Office 365 or on-premise exchange server from which to execute the compliance actions E.G. https://management.exchangelabs.com/Management|None|

Troubleshooting

Queries are expected to be wrapped in quotes e.g. subject:"a subject"

Workflows

Examples:

  • Block an email or domain for an organization

Versions

  • 1.0.0 - Initial plugin
  • 1.0.1 - Fix issue where plugin would fail when creating transport rule on first run
  • 2.0.0 - New actions Mass Search, Purge and combined Search and Purge
  • 2.1.0 - Add user email address array to Search action
  • 2.2.0 - New action Message Trace

References

Custom Output Types

This plugin does not contain any custom output types.

plugin_spec_version: v2
name: microsoft_office365_email_security
title: Microsoft Office365 Email Security
description: A collection of utilities related to Office 365 email security tasks
version: 2.2.0
vendor: rapid7
status: ["supported"]
tags:
- Office365
- Microsoft
- Administration
- Spam
- Phishing
- Remediation
- Email

types:
  message_trace:
    Organization:
      type: string
      title: "Organization"
      description: "Organization that message trace was run on"
      required: true
    MessageId:
      title: "Message ID"
      type: string
      description: "ID of found email"
      required: true
    Received:
      title: "Received Date"
      type: string
      description: "Date email was received"
      required: true
    RecipientAddress:
      title: "Recipient Address"
      description: "Recipient address"
      required: true
      type: string
    Subject:
      title: "Subject"
      description: "Subject"
      required: true
      type: string
    SenderAddress:
      title: "Sender Address"
      description: "Sender address"
      required: true
      type: string

connection: 
  credentials:
    type: credential_username_password
    title: Credentials
    description: Username and password
    required: true
  office_365_url:
    title: Office 365 URL
    description: This parameter sets the location of the Office 365 or on-premise exchange server from which to execute the compliance actions E.G. https://management.exchangelabs.com/Management
    type: string
    default: https://ps.compliance.protection.outlook.com/powershell-liveid/
    required: true

actions:
  block_sender_transport_rule:
    title: Block Sender Transport Rule
    description: Add a domain or email address to a blocking transport rule in Exchange Admin Center
    input:
      domain_or_email_to_block:
        title: Domain or Email to Block
        type: string
        description: Domain or email address to block
        required: true
      transport_rule_name: 
        title: Transport Rule Name
        description: Transport rule name
        type: string
        default: "InsightConnect Block List"
        required: true
    output:
      result:
        title: Result
        description: Result
        type: string
        required: true
  mass_search_and_purge:
    title: Email Compliance Search and Purge
    description: Search and purge a provided email
    input:
      compliance_search_name:
        title: Compliance Search Name
        type: string
        description: Name of compliance search
        required: true
      content_match_query: 
        title: Content Match Query
        description: This parameter uses a text search string or a query that's formatted by using the Keyword Query Language (KQL). For more information about KQL, see Keyword Query Language syntax reference (https://go.microsoft.com/fwlink/p/?linkid=269603)
        type: string
        required: true
      query_timeout:
        title: Query Timeout
        type: integer
        description: Query timeout in minutes
        default: 60
        required: false
      delete_items:
        title: Delete Items
        description: The script only executes the delete action if this parameter is true
        type: boolean
        default: false
        required: false
    output:
      success:
        title: Success
        description: Success
        type: boolean
        required: true
  email_compliance_search:
    title: Email Compliance Search
    description: Create a compliance search for provided email
    input:
      compliance_search_name:
        title: Compliance search name
        type: string
        description: Name of compliance search
        required: true
      content_match_query: 
        title: Content Match Query
        description: This parameter uses a text search string or a query that's formatted by using the Keyword Query Language (KQL). For more information about KQL, see Keyword Query Language syntax reference (https://go.microsoft.com/fwlink/p/?linkid=269603)
        type: string
        required: true
      query_timeout:
        title: Query Timeout
        type: integer
        description: Query timeout in minutes
        default: 60
        required: false
    output:
      affected_users:
        title: Users
        description: Number of affected users
        type: integer
        required: true
      users:
        title: User Email Addresses
        description: Email address of all affected users
        type: "[]string"
        required: true
      emails_found:
        title: Emails found
        description: Emails found that matched
        type: integer
        required: true
  mass_purge:
    title: Email Compliance Purge
    description: Purge a provided email
    input:
      compliance_search_name:
        title: Compliance search name
        type: string
        description: Name of compliance search
        required: true
      query_timeout:
        title: Query Timeout
        type: integer
        description: Query timeout in minutes
        default: 60
        required: false
    output:
      success:
        title: Success
        description: Success
        type: boolean
        required: true
  message_trace:
    title: Message Trace
    description: Run a message trace
    input:
      Sender_address:
        title: Sender Address
        type: string
        description: Sender address
        required: true
      start_date:
        title: Start Date
        type: string
        description: Start date in format MM/DD/YYYY e.g. 09/27/2019
        required: true
      end_date:
        title: End Date
        type: string
        description: End date in format MM/DD/YYYY e.g. 09/27/2019
        required: true
    output:
      message_traces:
        title: Message Traces
        description: Message Trace results
        type: "[]message_trace"
        required: true
Other plugins
BMC Remedy ITSM
Rapid7   |   v1.7.0
Plugin
Get
String Operations
Rapid7   |   v1.2.0
Plugin
Get
Microsoft Teams
Rapid7   |   v1.2.2
Plugin
Get
HTML
Rapid7   |   v1.2.0
Plugin
Get
Active Directory LDAP
Rapid7   |   v3.2.6
Plugin
Get