# msticpy: Microsoft's Python security library for Jupyter threat hunting and investigation

> msticpy is Microsoft's Python library for security investigation and hunting in Jupyter Notebooks, with support for Sentinel, Splunk and OData log queries, threat intelligence enrichment and Indicators of Activity extraction. PyPI publishing is currently halted, requiring installation directly from the GitHub repository.

**microsoft/msticpy** — Microsoft Threat Intelligence Security Tools

- Repository: https://github.com/microsoft/msticpy
- Stars: 2,012 · Forks: 341
- Language: Python
- License: NOASSERTION
- Published: 2026-10-11 · Updated: 2026-10-11 · Language: en
- Canonical page: https://hysenlabs.com/projects/microsoft-msticpy

## PyPI publishing is halted due to supply chain security controls; use the GitHub install path

The README opens with a notice about a temporary publishing halt on PyPI. Supply chain security controls have blocked the maintainers from updating the PyPI package, and the README says the backlog includes security-related fixes. Until the block is lifted, the recommended approach is to install directly from the repository:

```bash
python -m pip install --upgrade --force-reinstall git+https://github.com/microsoft/msticpy.git
```

An alternative using uv is:

```bash
uv pip install git+https://github.com/microsoft/msticpy.git
```

Once the PyPI block clears, the standard path returns:

```bash
pip install msticpy
```

For upgrades, the README gives `pip install --upgrade msticpy`. One note accompanies the upgrade: msticpyconfig.yaml, the package's configuration file, should be stored outside the msticpy install directory and referenced via an environment variable. An upgrade that replaces the install directory will otherwise overwrite the configuration.

## QueryProvider targets Sentinel, XDR, Splunk and OData with parameterized YAML queries

QueryProvider is the data acquisition layer. It connects to Microsoft Sentinel and Log Analytics, Microsoft XDR, Splunk and OData sources, and also supports Mordor datasets and local data in CSV or pickled DataFrame format. Built-in parameterized queries let a security analyst run complex queries from a single function call, and custom queries can be added through a YAML schema.

Pandas DataFrames are the common output format across almost all components. This means the result of a QueryProvider call is immediately available for pandas operations, for enrichment, or for visualization without a conversion step. The README says work is in progress to add support for further SIEM platforms.

The choice to center on pandas means the library is built for analysts who are comfortable with DataFrame-oriented workflows. It is not designed as a REST client or a batch pipeline component that operates outside a notebook environment.

## TILookup queries AlienVault OTX, IBM XForce, VirusTotal and Azure Sentinel for IoC enrichment

Threat intelligence enrichment goes through the TILookup class. Built-in providers cover AlienVault OTX, IBM XForce, VirusTotal and Azure Sentinel. Input is a single IoC observable or a pandas DataFrame containing multiple observables.

Some providers require an account and an API key. Free tiers at several providers enforce throttling, which the README says might affect bulk lookups. This is the practical limit for large-scale IoC enrichment: the throughput is bounded by the TI provider's rate limits, and the library does not document a retry or queue mechanism for hitting those limits.

Alongside TI enrichment, GeoIP lookups are available through two backends: GeoLiteLookup, which uses the MaxMind GeoLite database, and IPStackLookup, which calls the IPStack API. Azure resource data arrives through the AzureData module, which pulls additional host details via the Azure API. AzureSentinel lets the analyst query incidents and retrieve detector and hunting queries, while AzureBlobStorage handles read and write operations to Azure Blob storage.

## msticpyconfig.yaml stores credentials and API keys and must be kept outside the install path

Configuration for msticpy lives in msticpyconfig.yaml. This file holds the credentials and API keys that connect QueryProvider and TILookup to external services. The README warns that upgrading msticpy by replacing the install directory will overwrite this file if it sits inside the msticpy package folder.

The recommended practice is to copy the config file to a location on disk outside the msticpy folder, then set an environment variable pointing to it. The README does not name the specific environment variable in the section given in this material, but it identifies the YAML file as the configuration source for the notebook environment and for query providers.

This also has a security implication: msticpyconfig.yaml holds live API keys in YAML format. Keeping it outside the package directory and outside version control is standard practice, but the README does not explicitly warn against committing it.

## Anomalous session detection and time series decomposition are part of the Security Analysis subpackage

Beyond data acquisition and enrichment, msticpy contains a Security Analysis subpackage for more involved investigation work. Two specific capabilities are named: anomalous session detection and time series decomposition.

The ml extras group in setup.py (not shown in full, but partially visible in the repository file extract) includes scikit-learn>=1.0.0, scipy>=1.1.0, statsmodels>=0.11.1 and rrcf==0.4.4 for the machine learning components. rrcf==0.4.4 is pinned to an exact version rather than a floor, which is unusual and means updates to that dependency require a version constraint change. The visualization side includes interactive timelines, process trees and multi-dimensional Morph Charts, rendered with bokeh>=3.0.0 and folium>=0.20.0 for map-based geolocation views.

v3.1.0, published on 2026-09-21 with a ScanMalware TI Provider and Python 3.14 support, is the current version, and the last push was on 2026-09-23.

## requirements.txt pins CVE-tracked transitive packages; the distribution terms have a classification gap between setup.py and GitHub

Several entries in requirements.txt carry inline comments flagging specific security vulnerabilities, for example aiohttp>=3.14.3 has the comment "(sec vuln) transitive dependency via geoip2" and tornado>=6.5.5 has a similar note. This means the version floors in the requirements.txt were set in response to known CVEs in transitive dependencies, which is traceable and explicit but also means the floor versions change when new CVEs appear.

setup.py's header says 'Licensed under the MIT License' while GitHub marks the repository terms as 'Other' rather than a standard identifier; anyone with distribution approval workflows should read the root terms document directly rather than relying on the setup.py comment alone.

## Pandas-first design and the Azure dependency graph limit use outside Jupyter investigations

Almost every component takes or returns a pandas DataFrame, which is practical for Jupyter-based investigation but makes the library ill-suited for server-side pipelines, REST APIs or batch jobs that do not use pandas. The library was developed to support Sentinel notebook authoring, and that origin shows in the design assumptions.

The core install's requirements.txt alone pulls in azure-common, azure-core, azure-identity, azure-keyvault-secrets, azure-kusto-data, azure-mgmt-core and a further set of azure-mgmt packages. A deployment that only needs Splunk or OData connectivity still installs the full Azure client stack. Selective extras exist in setup.py for Splunk, SumoLogic and SQL conversion, but core Azure dependencies are in the base install rather than those extras.

SASRec-style tools that address pure event-stream analysis without the Azure enrichment layer would need a different library entirely. For standalone Python scripts outside Jupyter, the library's interactive widgets, timeline visualizations and notebook widgets are dead weight.

## Conclusion

Use msticpy if your team investigates threats in Jupyter Notebooks against Microsoft Sentinel or Splunk, and the dependency weight of the Azure and visualization stack is acceptable. Skip it for environments outside the Microsoft ecosystem or for pipelines where Jupyter is not part of the workflow, since the library's design centers on notebook-first interactive investigation. Before adopting, confirm that the PyPI publication block has been resolved and that the version available at PyPI matches the GitHub repository's main branch; until then, the GitHub install path is the only one with current security fixes.

## FAQ

### How do I install msticpy?

PyPI publishing is currently halted, so install from GitHub with python -m pip install --upgrade --force-reinstall git+https://github.com/microsoft/msticpy.git or via uv pip install git+https://github.com/microsoft/msticpy.git. Once the PyPI block is resolved, pip install msticpy returns to being the standard path.

### What data sources does msticpy support?

QueryProvider connects to Microsoft Sentinel and Log Analytics, Microsoft XDR, Splunk, OData sources, Mordor datasets, and local CSV or pickled DataFrame files. The README says work is in progress to add support for further SIEM platforms.

### What threat intelligence providers does msticpy include?

TILookup has built-in providers for AlienVault OTX, IBM XForce, VirusTotal and Azure Sentinel. Some require an account and an API key, and free-tier providers enforce throttling that may affect bulk IoC lookups.

### Where should I store msticpyconfig.yaml?

The README advises storing msticpyconfig.yaml outside the msticpy install directory and referencing it via an environment variable. Keeping it inside the install directory risks losing it when upgrading msticpy.

### What is the licence for msticpy?

The setup.py header says 'Licensed under the MIT License' and points to License.txt. GitHub classifies the licence as 'Other' because its classifier cannot map the LICENSE file to a standard identifier, so anyone with licence approval requirements should read the full LICENSE file directly.

## Sources

- [Issues](https://github.com/microsoft/msticpy/issues)
- [microsoft/msticpy on GitHub](https://github.com/microsoft/msticpy)
- [README](https://github.com/microsoft/msticpy/blob/main/README.md)
- [Releases](https://github.com/microsoft/msticpy/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/microsoft-msticpy