/Auto-Security-Incident-Creation-From-New-Suspect-Emails

Solution to auto create new incidents on Archer Security platform based on new suspect emails

Primary LanguagePythonMIT LicenseMIT

Auto Incidents Creation From Suspect New Suspect Emails on Archer Security Incidents Platform

This project aims to automate the process of creating new incidents on Archer security incidents platform by collecting suspicious e-mails from a mailbox and creating a new incident report on the platform, with all required fields covered by the automation

Solution created using Python Language, Microsoft Graph API, python-o365 library to collect e-mails and acess mailbox and Archer API to open new incidents on the platform.

Author

👤 Antonio Costa

Contributing

Contributions, issues and feature requests are welcome!

Show your support

Give a ⭐️ if this project helped you!

License

Copyright © 2022 Antonio Costa.
This project is MIT licensed.

Index

Creating an application on Microsoft Azure

Creating the application it's necessary to enable the reading permission of user's email.

With the creation of the application, it's possible to read any email account within the box, only possessing the application ID, the tenant ID and the secret key ID.*

Note: Only Azure administrators can create new applications unless the permission of creating new applications has been released to users.*

For app creation, the following steps should be followed:

1 - Application creation on Microsoft Azure

For access to email, it's necessary to create an application in Microsoft Azure Directory, with application permission to access the email reading permittions

For app creation, the user must follow the following steps:

  1. Access portal azure

  2. Access Azure Active Directory

  3. Application registration

  4. Give a name to the application

  5. In types of accounts supported, select Accounts in this organizational directory only (tenant name only - Single tenant)

Note:

  • Selecting Accounts in this organizational directory only (tenant name only - Single tenant) only tenant accounts can access the app

  • If someone outside the tenant tries to acess the application, the follow error will be generated: "You cannot sign in here with a personal account. Instead, use your school or professional account."

  1. Selecting Platform, Web Application

  2. Within url redirecting, select the address https://login.microsoftonline.com/common/oauth2/nativeclient

  3. Register the app

  4. Collect the application ID (client) and the tenant ID (directory).

2 - Generating a secret key

  1. On app registrations, Certificates & secrets
  2. New client secret
  3. Select a validate time
  4. Add
  5. Copy the value of ID¹

² The value of the ID is only possible to preview once, so the value of the ID should be collected immediately after the creation of it.

3 - Adding new permissions

  1. API permissions
  2. Add a permision
  3. Microsoft Graph
  4. Delegated permissions
  5. Search for mail and select All Read permissions that you want.
  6. Add permissions.

Setting application

1 - Edit environment file

  1. Create a file named .env
  2. Copy all content from .env.example to .env file
  3. Edit the .env environment file
  4. Within the file, edit the APPLICATION_ID, SECRET_ID and TENANT_ID values, with the collected values of the creation of the application.
  5. Also edit the ACCOUNT_TO_ACESS variable with the email address to be read.¹

¹This option it's necessary on case the mail is a shared mail

2 - Archer API

There is a Archer API file .json on ./Archer/ArcherAPI/example_API.json

You must replace the API with informatios from your Archer System.

Start application

After following the previous steps, we need to install the project dependencies

pip3 install -r requirements.txt

If you want to run the application in a simple way you can run the command

python3 main.py

If you want your application to run as a background process:

sh start_restart_application.sh

This script will start to run the application as a background process.

OBS:

  • At the moment, this solution only runs on Linux servers, and in the future I will create an equal Windows solution.

At the first time you run your application a message asking for an access token will emerge.

https://login.microsoftonline.com/...
Paste the authenticated url here:
  1. To add acess the mailbox, you must acess the link token generated on the terminal screen
  2. If it is the first time accessing the application, it will be asked about what the app wants to do, and in our case, perform the reading of the mailbox.
  3. If you are repeating the process, nothing will be erased.
  4. In both cases, a new url will be generated in the browser.
  5. Collect the URL and paste the terminal.
  6. If all happened well, the following message would appear in the terminal.
Authentication Flow Completed. Oauth Access Token Stored. You can now use the API.

For this project, after the 90 days, a new access token must be generated, repeating the errors of the previous session.

And now everytime the mailbox receives a new email automatically the solution will create a new incident on Archer platform

If you don't want to follow this 90 days rule, feel free to read the oficial documentation.

References

Oficial documentation

python-o365