# Pandora Imap

# Introduction

**Ver.** 12-07-2022

Plug-in with which you can filter mails and the number of mails that match the filters used.

**Type**: Server or agent plug-in

# Compatibility matrix

<table border="1" id="bkmrk-sistemas-donde-se-ha"><tbody><tr><td>**Systems where tested**</td><td>Fedora

</td></tr><tr><td>**Systems where it should work**</td><td>Any linux system

</td></tr></tbody></table>

# Prerequisites

- Pandora FMS Data Server enabled
- Pandora FMS Plugin Server enabled.
- Have python3 installed
- Install the following python libraries

<div id="bkmrk-imap_tools"><div>**imap\_tools**</div><div></div></div>```
pip install imap_tools
```

<div id="bkmrk-python3%C2%A0">python3 </div><div id="bkmrk-"></div>```
pip3 install imap_tools
```

**Cryptocode**

```
pip install cryptocode
```

python3

```
pip3 install cryptocode
```

# Parameters

<table border="1" id="bkmrk-par%C3%A1metro-descripci%C3%B3"><tbody><tr style="height: 29px;"><td style="width: 135.094px; height: 29px;">--server</td><td style="width: 490.141px; height: 29px;">Example: <div><div>outlook.office365.com</div></div></td></tr><tr style="height: 29px;"><td style="width: 135.094px; height: 29px;">--user</td><td style="width: 490.141px; height: 29px;">User's e-mail address</td></tr><tr style="height: 29px;"><td style="width: 135.094px; height: 29px;">--password</td><td style="width: 490.141px; height: 29px;">User password</td></tr><tr style="height: 29px;"><td style="width: 135.094px; height: 29px;">--list</td><td style="width: 490.141px; height: 29px;">To list all mailboxes</td></tr><tr style="height: 29px;"><td style="width: 135.094px; height: 29px;">--mailbox</td><td style="width: 490.141px; height: 29px;">To choose mailbox to filter on (Inbox by default)</td></tr><tr style="height: 29px;"><td style="width: 135.094px; height: 29px;">--subject</td><td style="width: 490.141px; height: 29px;">To filter word or phrase in the subject.</td></tr><tr style="height: 29px;"><td style="width: 135.094px; height: 29px;">--from\_mail</td><td style="width: 490.141px; height: 29px;">To filter by e-mail</td></tr><tr style="height: 29px;"><td style="width: 135.094px; height: 29px;">--date</td><td style="width: 490.141px; height: 29px;">To filter from a certain date (example: '2020,1,1')</td></tr><tr style="height: 29px;"><td style="width: 135.094px; height: 29px;">--body</td><td style="width: 490.141px; height: 29px;">To filter by a word in the body</td></tr><tr style="height: 29px;"><td style="height: 29px; width: 135.094px;">--mail\_list</td><td style="height: 29px; width: 490.141px;">To create a new module with a list of matching mails.</td></tr><tr style="height: 29px;"><td style="height: 29px; width: 135.094px;">--tentacle\_port</td><td style="height: 29px; width: 490.141px;">Tentacle port in case you want to send the data in this way</td></tr><tr style="height: 29px;"><td style="height: 29px; width: 135.094px;">--tentacle\_address</td><td style="height: 29px; width: 490.141px;">Tentacle address in case you want to send the data in this way</td></tr><tr style="height: 29px;"><td style="height: 29px; width: 135.094px;">--agent\_name</td><td style="height: 29px; width: 490.141px;">Name of the agent that will contain the modules</td></tr><tr style="height: 29px;"><td style="height: 29px; width: 135.094px;">-g,--group</td><td style="height: 29px; width: 490.141px;">Target group in pandora</td></tr><tr style="height: 29px;"><td style="height: 29px; width: 135.094px;">--data\_dir</td><td style="height: 29px; width: 490.141px;">Data destination address</td></tr><tr style="height: 29px;"><td style="height: 29px; width: 135.094px;">--as\_agent\_plugin</td><td style="height: 29px; width: 490.141px;">Agent mode when activated with a 1</td></tr></tbody></table>

# Manual execution

The plugin creates an agent with two modules for each execution, one with the number of emails that match the filtering and another with the list of these emails. The filtering parameters are the following:

`--subject`

`--body`

`--from_mail`

`--date`

You can filter by any of these or you can combine them as follows:

subject + body

subject + body + from\_mail

subject + body + from\_mail + date

You can select mails from any mailbox (inbox by default), to see a list of the mailboxes of the mail you can use the parameter

`--list 1`

<p class="callout warning">The user and password will only need to be entered the first time, in a manual execution, then a file will be created that will store the encrypted credentials and the plugin will read them from this file.</p>

``

```
python3 pandora_imap.py --server <server> --user <user> --password <password> --list 1
```

[![image-1658928329496.png](https://pandorafms.com/guides/public/uploads/images/gallery/2022-07/scaled-1680-/image-1658928329496.png)](https://pandorafms.com/guides/public/uploads/images/gallery/2022-07/image-1658928329496.png)

```
python3 pandora_imap.py --server <server> --user <user> --password <password> --subject <subject> --body <body> --as_agent_plugin 1
```

**Manual execution example**

[![image-1658928348665.png](https://pandorafms.com/guides/public/uploads/images/gallery/2022-07/scaled-1680-/image-1658928348665.png)](https://pandorafms.com/guides/public/uploads/images/gallery/2022-07/image-1658928348665.png)

**Example help menu** [![image-1658928383815.png](https://pandorafms.com/guides/public/uploads/images/gallery/2022-07/scaled-1680-/image-1658928383815.png)](https://pandorafms.com/guides/public/uploads/images/gallery/2022-07/image-1658928383815.png)

**Example with all filters**

[![image-1658928418619.png](https://pandorafms.com/guides/public/uploads/images/gallery/2022-07/scaled-1680-/image-1658928418619.png)](https://pandorafms.com/guides/public/uploads/images/gallery/2022-07/image-1658928418619.png)

# Configuration in PandoraFMS

**Manual installation**

Go to servers &gt; plugins:

[![image-1629974405286.png](https://pandorafms.com/guides/public/uploads/images/gallery/2021-08/scaled-1680-/image-1629974405286.png)](https://pandorafms.com/guides/public/uploads/images/gallery/2021-08/image-1629974405286.png)

Click on add:

[![image-1629974430627.png](https://pandorafms.com/guides/public/uploads/images/gallery/2021-08/scaled-1680-/image-1629974430627.png)](https://pandorafms.com/guides/public/uploads/images/gallery/2021-08/image-1629974430627.png)

We put the name and description of your choice:

[![image-1658834125705.png](https://pandorafms.com/guides/public/uploads/images/gallery/2022-07/scaled-1680-/image-1658834125705.png)](https://pandorafms.com/guides/public/uploads/images/gallery/2022-07/image-1658834125705.png)

We enter as command the execution with the path of the plugin:

```
python3 </path_pandora_imap>
```

<p class="callout info align-center">Remember that the recommended path for the use of the server plugins is: /usr/share/pandora\_server/util/plugin/</p>

[![image-1659089658886.png](https://pandorafms.com/guides/public/uploads/images/gallery/2022-07/scaled-1680-/image-1659089658886.png)](https://pandorafms.com/guides/public/uploads/images/gallery/2022-07/image-1659089658886.png)

<p class="callout warning">Remember that you must run the plugin manually with user and password for the first time to create an imap\_credentials.txt file that will save the encrypted credentials.</p>

And in plugin parameters we will introduce these followed by the macro "\_field&lt;N&gt;\_", the mandatory ones for the plugin to work are --server, (--user, --password must be introduced in a first manual execution only the first time) and at least one of the parameters used for filtering.

<p class="callout warning">Although it is not mandatory, the use of the --agent\_name parameter is highly recommended, since it allows us to customize the name of the agent that will contain the created modules.</p>

**--SERVER**

[![image-1658834684259.png](https://pandorafms.com/guides/public/uploads/images/gallery/2022-07/scaled-1680-/image-1658834684259.png)](https://pandorafms.com/guides/public/uploads/images/gallery/2022-07/image-1658834684259.png)

**--SUBJECT**

[![image-1658834761517.png](https://pandorafms.com/guides/public/uploads/images/gallery/2022-07/scaled-1680-/image-1658834761517.png)](https://pandorafms.com/guides/public/uploads/images/gallery/2022-07/image-1658834761517.png)

**--BODY**

[![image-1658834783278.png](https://pandorafms.com/guides/public/uploads/images/gallery/2022-07/scaled-1680-/image-1658834783278.png)](https://pandorafms.com/guides/public/uploads/images/gallery/2022-07/image-1658834783278.png)

Once this is done, we will click on "create".

Once this is done, the only thing left to do is to call it, so we will go to some agent's view and create an add-in module:

[![image-1646741530197.png](https://pandorafms.com/guides/public/uploads/images/gallery/2022-03/scaled-1680-/image-1646741530197.png)](https://pandorafms.com/guides/public/uploads/images/gallery/2022-03/image-1646741530197.png)

We will give it a name and in the section "plugin" we will put the one we have just configured.

[![image-1658834560870.png](https://pandorafms.com/guides/public/uploads/images/gallery/2022-07/scaled-1680-/image-1658834560870.png)](https://pandorafms.com/guides/public/uploads/images/gallery/2022-07/image-1658834560870.png)

Once this is done, click on create.

If the module is shown with 1, it means that it is running correctly.

# Modules generated by the plugin

The plugin will create a module called "Coincidences\_count" with the number of coincidences and if the ``--mail\_list`` parameter is used it will also create a module with a list of coincidences.

[![image-1658831113098.png](https://pandorafms.com/guides/public/uploads/images/gallery/2022-07/scaled-1680-/image-1658831113098.png)](https://pandorafms.com/guides/public/uploads/images/gallery/2022-07/image-1658831113098.png)

 **List module view**

[![image-1658831122550.png](https://pandorafms.com/guides/public/uploads/images/gallery/2022-07/scaled-1680-/image-1658831122550.png)](https://pandorafms.com/guides/public/uploads/images/gallery/2022-07/image-1658831122550.png)