├── .gitignore ├── LICENSE ├── MANIFEST.in ├── README.md ├── requirements.txt ├── setup.py └── sophos_central_api_connector ├── config ├── intelix_config.ini ├── misp_config.ini ├── sophos_central_api_config.py ├── sophos_config.ini └── splunk_config.ini ├── docs ├── alerts.md ├── get_admins.md ├── get_firewall_groups.md ├── get_firewalls.md ├── get_roles.md ├── intelix.md ├── intelix_configuration.md ├── inventory.md ├── ioc_hunter.md ├── local_sites.md ├── misp_configuration.md ├── sophos_configuration.md └── splunk_configuration.md ├── get_admins.py ├── get_firewall_groups.py ├── get_firewalls.py ├── get_roles.py ├── ioc_hunter.py ├── queries ├── live_discover_queries │ └── ld_ioc_hunter.sql └── xdr_queries │ └── xdr_ioc_hunter.sql ├── sophos_central_api_auth.py ├── sophos_central_api_awssecrets.py ├── sophos_central_api_connector_utils.py ├── sophos_central_api_delete_data.py ├── sophos_central_api_get_data.py ├── sophos_central_api_intelix.py ├── sophos_central_api_live_discover.py ├── sophos_central_api_output.py ├── sophos_central_api_polling.py ├── sophos_central_api_tenants.py ├── sophos_central_hec_splunk.py └── sophos_central_main.py /.gitignore: -------------------------------------------------------------------------------- 1 | # Byte-compiled / optimized / DLL files 2 | __pycache__/ 3 | *.py[cod] 4 | *$py.class 5 | 6 | # C extensions 7 | *.so 8 | 9 | # Distribution / packaging 10 | .Python 11 | build/ 12 | develop-eggs/ 13 | dist/ 14 | downloads/ 15 | eggs/ 16 | .eggs/ 17 | lib/ 18 | lib64/ 19 | parts/ 20 | sdist/ 21 | var/ 22 | wheels/ 23 | *.egg-info/ 24 | .installed.cfg 25 | *.egg 26 | MANIFEST 27 | 28 | # PyInstaller 29 | # Usually these files are written by a python script from a template 30 | # before PyInstaller builds the exe, so as to inject date/other infos into it. 31 | *.manifest 32 | *.spec 33 | 34 | # Installer logs 35 | pip-log.txt 36 | pip-delete-this-directory.txt 37 | 38 | # Unit test / coverage reports 39 | htmlcov/ 40 | .tox/ 41 | .coverage 42 | .coverage.* 43 | .cache 44 | nosetests.xml 45 | coverage.xml 46 | *.cover 47 | .hypothesis/ 48 | .pytest_cache/ 49 | 50 | # Translations 51 | *.mo 52 | *.pot 53 | 54 | # Django stuff: 55 | *.log 56 | local_settings.py 57 | db.sqlite3 58 | 59 | # Flask stuff: 60 | instance/ 61 | .webassets-cache 62 | 63 | # Scrapy stuff: 64 | .scrapy 65 | 66 | # Sphinx documentation 67 | sophos_central_api_connector/docs/_build/ 68 | 69 | # PyBuilder 70 | target/ 71 | 72 | # Jupyter Notebook 73 | .ipynb_checkpoints 74 | 75 | # pyenv 76 | .python-version 77 | 78 | # celery beat schedule file 79 | celerybeat-schedule 80 | 81 | # SageMath parsed files 82 | *.sage.py 83 | 84 | # Environments 85 | .env 86 | .venv 87 | env/ 88 | venv/ 89 | ENV/ 90 | env.bak/ 91 | venv.bak/ 92 | 93 | # Spyder project settings 94 | .spyderproject 95 | .spyproject 96 | 97 | # Rope project settings 98 | .ropeproject 99 | 100 | # mkdocs documentation 101 | /site 102 | 103 | # mypy 104 | .mypy_cache/ 105 | .DS_Store -------------------------------------------------------------------------------- /MANIFEST.in: -------------------------------------------------------------------------------- 1 | recursive-include sophos_central_api_connector *.ini *.py *.md *.sqlite -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Sophos Central API Connector 2 | Python library to utilise many of the features in Sophos Central API across multiple or single tenants 3 | 4 | * [Documentation: Sophos Central API](https://developer.sophos.com/) 5 | * [Documentation: Sophos Central API Connector](https://github.com/sophos-cybersecurity/sophos-central-api-connector/tree/master/sophos_central_api_connector/docs) 6 | 7 | ![Python](https://img.shields.io/badge/python-v3.6+-blue.svg) 8 | [![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0) 9 | [![Generic badge](https://img.shields.io/badge/version-0.1.6-green.svg)](https://shields.io/) 10 | ___ 11 | 12 | ## Table of contents: 13 | 14 | - [Sophos Central API Connector](#sophos-central-api-connector) 15 | * [Features](#features) 16 | * [Quick start](#quick-start) 17 | - [**Important!**](#--important---) 18 | * [Prerequisites](#prerequisites) 19 | * [Install](#install) 20 | * [Authentication](#authentication) 21 | + [Static Credentials](#static-credentials) 22 | + [AWS Secrets Manager](#aws-secrets-manager) 23 | * [Basic Examples](#basic-examples) 24 | + [Help](#help) 25 | + [Tenants List](#tenants-list) 26 | + [Inventory](#inventory) 27 | + [Alerts/Event Information](#alerts-event-information) 28 | + [Local Site](#local-site) 29 | * [Output Options](#output-options) 30 | * [Troubleshooting](#troubleshooting) 31 | * [Structure](#structure) 32 | 33 | ___ 34 | 35 | ## Features 36 | All features can be run against single or multiple tenants 37 | * Gather tenant system inventory 38 | * Output to stdout, json, Splunk 39 | * Gather alerts 40 | * Alert polling 41 | * Output to stdout, json, Splunk 42 | * Local Sites 43 | * Clean up Global exclusions 44 | * Compare exclusions to SophosLabs Intelix 45 | * Generate report 46 | * IOC Hunting - Utilising Live Discover or XDR DataLake 47 | * MISP Attribute hunting (eventId, tags) 48 | * RAW JSON input 49 | * Saved search 50 | 51 | ___ 52 | 53 | ## Quick start 54 | Want to test as quickly as possible? Follow the below quick start steps to begin looking at your Sophos Central data! 55 | 1. Install latest version of Python 3 56 | 1. Create a folder e.g "sophos_test" 57 | 1. Open a command prompt/terminal 58 | 1. Create a Python Virtual Environment: 59 | ```commandline 60 | python -m venv 61 | ``` 62 | 1. Activate the Python Virtual Environment: 63 | ```commandline 64 | \Scripts\activate 65 | ``` 66 | 1. Install the Sophos Central API Connector (this will also install the requirements): 67 | ```commandline 68 | pip install sophos-central-api-connector 69 | ``` 70 | 1. Once it has finished installing browse to: 71 | ```commandline 72 | cd \Lib\site-packages\sophos_central_api_connector 73 | ``` 74 | 1. Run the following command to view help to begin: 75 | ```commandline 76 | python sophos_central_main.py --help 77 | ``` 78 | 1. Add your Sophos Central API id and secret to the sophos_config.ini under the folder: \Lib\site-packages\sophos_central_api_connector\config 79 | 80 | > #### **Important!** 81 | > We would recommend that the static entry is only used for testing purposes and the token is stored and accessed securely. 82 | > Please reference the authentication section 83 | ___ 84 | 85 | ## Prerequisites 86 | In order to use the package you will require a valid API key from your Sophos Central tenant. To obtain a valid API key please reference the documentation [here](https://developer.sophos.com/intro) 87 | ___ 88 | 89 | ## Install 90 | ```commandline 91 | pip install --user sophos_central_api_connector 92 | ``` 93 | ___ 94 | 95 | ## Authentication 96 | There are two options for authentication, the setting used here will be used for all areas of authentication. As mentioned under the configuration section we recommend using the AWS Secrets Manager for storing these credentials. Only use the static credentials for testing purposes. 97 | 98 | ### Static Credentials 99 | To specify using the static credentials which are in the \*config.ini files you can use the following: 100 | `python3 sophos_central_main.py --auth static` 101 | 102 | ### AWS Secrets Manager 103 | To specify using the AWS settings which are in the \*config.ini files to retrieve the secrets and token you can use the following: 104 | `python3 sophos_central_main.py --auth aws` 105 | ___ 106 | 107 | ## Basic Examples 108 | 109 | ### Help 110 | To get information on the CLI commands when using the `sophos_central_main.py` run: 111 | 112 | ```commandline 113 | python sophos_central_main.py --help 114 | ``` 115 | 116 | ### Tenants List 117 | To get a list of tenants: 118 | 119 | ```commandline 120 | python sophos_central_main.py --auth --get tenants 121 | ``` 122 | 123 | ### Inventory 124 | To get inventory data: 125 | ```commandline 126 | python sophos_central_main.py --auth --get inventory --output 127 | ``` 128 | 129 | ### Alerts/Event Information 130 | To get alert data: 131 | ```commandline 132 | python sophos_central_main.py --auth --get alerts --days --output 133 | ``` 134 | 135 | ### Local Site 136 | To get a list of local site data: 137 | ```commandline 138 | python sophos_central_main.py --auth --get local-sites --output 139 | ``` 140 | ___ 141 | 142 | ## Output Options 143 | There are four output options available for the inventory, simply add one of the following after `--output`: 144 | - **stdout:** Print the information to the console. 145 | - **json:** Save the output of the request to a json file 146 | - **splunk:** This will send the data to Splunk with no changes made. This will apply the settings made in the transform files. 147 | - **splunk_trans:** Using this output will apply the information set in the splunk_config.ini for the host, source and sourcetype. This will overrun the settings in the transform files in Splunk but not the Index that the data should be sent to. 148 | 149 | ___ 150 | 151 | ## Troubleshooting 152 | All logging is done via the python `logging` library. Valid logging levels are: 153 | 154 | - INFO 155 | - DEBUG 156 | - CRITICAL 157 | - WARNING 158 | - ERROR 159 | 160 | For basic feedback set the logging level to `INFO` 161 | ___ 162 | 163 | ## Structure 164 | Below is the structure after installing through pip: 165 | ``` 166 | sophos_central_api_connector 167 | | .gitignore 168 | | LICENSE 169 | | MANIFEST.in 170 | | README.md 171 | | requirements.txt 172 | | setup.py 173 | |___docs 174 | | alerts.md 175 | | intelix.md 176 | | intelix_configuration.md 177 | | inventory.md 178 | | ioc_hunter.md 179 | | local_sites.md 180 | | misp_configuration.md 181 | | sophos_configuration.md 182 | | splunk_configuration.md 183 | |___queries 184 | | |___live_discover_queries 185 | | ld_ioc_hunter.sql 186 | | |___xdr_queries 187 | | xdr_ioc_hunter.sql 188 | |___sophos_central_api_connector 189 | | ioc_hunter.py 190 | | sophos_central_api_live_discover.py 191 | | sophos_central_api_auth.py 192 | | sophos_central_api_awssecrets.py 193 | | sophos_central_api_connector_utils.py 194 | | sophos_central_api_delete_data.py 195 | | sophos_central_api_get_data.py 196 | | sophos_central_api_intelix.py 197 | | sophos_central_api_output.py 198 | | sophos_central_api_polling.py 199 | | sophos_central_api_tenants.py 200 | | sophos_central_api_hec_splunk.py 201 | | sophos_central_main.py 202 | | get_admins.py 203 | | get_roles.py 204 | | get_firewall_groups.py 205 | | get_firewalls.py 206 | |___config 207 | | intelix_config.ini 208 | | misp_config.ini 209 | | sophos_central_api_config.py 210 | | sophos_config.ini 211 | | splunk_config.ini 212 | ``` 213 | 214 | Below is the structure with all the files that are created through different mechanisms: 215 | ``` 216 | sophos_central_api_connector 217 | | .gitignore 218 | | LICENSE 219 | | MANIFEST.in 220 | | README.md 221 | | requirements.txt 222 | | setup.py 223 | |___sophos_central_api_connector 224 | | |___docs 225 | | | alerts.md 226 | | | intelix.md 227 | | | intelix_configuration.md 228 | | | inventory.md 229 | | | ioc_hunter.md 230 | | | local_sites.md 231 | | | misp_configuration.md 232 | | | sophos_configuration.md 233 | | | splunk_configuration.md 234 | |___queries 235 | | |___live_discover_queries 236 | | ld_ioc_hunter.sql 237 | | |___xdr_queries 238 | | xdr_ioc_hunter.sql 239 | | ioc_hunter.py 240 | | sophos_central_api_live_discover.py 241 | | sophos_central_api_auth.py 242 | | sophos_central_api_awssecrets.py 243 | | sophos_central_api_connector_utils.py 244 | | sophos_central_api_delete_data.py 245 | | sophos_central_api_get_data.py 246 | | sophos_central_api_intelix.py 247 | | sophos_central_api_output.py 248 | | sophos_central_api_polling.py 249 | | sophos_central_api_tenants.py 250 | | sophos_central_api_hec_splunk.py 251 | | sophos_central_main.py 252 | | get_admins.py 253 | | get_roles.py 254 | | get_firewall_groups.py 255 | | get_firewalls.py 256 | |___config 257 | | intelix_config.ini 258 | | misp_config.ini 259 | | sophos_central_api_config.py 260 | | sophos_config.ini 261 | | splunk_config.ini 262 | |___logs 263 | | failed_events.json 264 | |___output 265 | | |___get_alerts 266 | | | _.json 267 | | | ... 268 | | |___get_inventory 269 | | | _.json 270 | | | ... 271 | | |___get_local_sites 272 | | | _.json 273 | | | ... 274 | | |___admin_data 275 | | | _.json 276 | | | ... 277 | | |___roles_data 278 | | | _.json 279 | | | ... 280 | | |_firewall_groups 281 | | | _.json 282 | | | ... 283 | | |_firewall_inventory 284 | | | _.json 285 | | | ... 286 | | |___intelix 287 | | |___delete_local_sites 288 | | _