Metadata-Version: 2.4
Name: netguard-threat-monitor
Version: 0.2.1
Summary: Embeddable HTTP threat monitoring, intrusion detection, and dashboards for Python applications
License: MIT License
        
        Copyright (c) 2026 NetGuard
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Keywords: security,intrusion-detection,http,monitoring,fastapi
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Topic :: Security
Classifier: License :: OSI Approved :: MIT License
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24.0
Requires-Dist: scikit-learn>=1.3.0
Requires-Dist: xgboost>=2.0.0
Requires-Dist: joblib>=1.3.0
Requires-Dist: click>=8.1.0
Requires-Dist: rich>=13.0.0
Requires-Dist: textual>=0.40.0
Requires-Dist: requests>=2.28.0
Provides-Extra: web
Requires-Dist: fastapi>=0.100.0; extra == "web"
Requires-Dist: django>=4.2.0; extra == "web"
Requires-Dist: uvicorn[standard]>=0.23.0; extra == "web"
Requires-Dist: httpx>=0.24.0; extra == "web"
Requires-Dist: python-multipart>=0.0.6; extra == "web"
Provides-Extra: flask
Requires-Dist: Flask>=2.3.0; extra == "flask"
Provides-Extra: train
Requires-Dist: pandas>=2.0.0; extra == "train"
Requires-Dist: imbalanced-learn>=0.11.0; extra == "train"
Requires-Dist: shap>=0.43.0; extra == "train"
Requires-Dist: optuna>=3.4.0; extra == "train"
Requires-Dist: matplotlib>=3.7.0; extra == "train"
Requires-Dist: seaborn>=0.12.0; extra == "train"
Requires-Dist: streamlit>=1.28.0; extra == "train"
Requires-Dist: scapy>=2.5.0; extra == "train"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: httpx>=0.24.0; extra == "dev"
Dynamic: license-file

# NetGuard

NetGuard is an embeddable HTTP threat monitoring SDK for Python applications.
It records request metadata, applies application-layer detection rules and a
bundled ML model, and provides an authenticated live dashboard.

## Documentation

Browse the [NetGuard documentation site](docs/index.html), the [API reference by install extra](docs/reference.html), and [copy-ready coding-agent prompts](docs/prompts.html) for installation,
framework integrations, dashboard setup, configuration, email alerts, CLI
commands, and deployment guidance. Preview it locally with:

    python -m http.server 8001 --directory docs

## Install

From a source checkout, run this command from the repository root:

```powershell
python -m pip install ".[web]"
```

After a release is published to PyPI, install the web integration with:

```powershell
python -m pip install "netguard-threat-monitor[web]"
```

## FastAPI integration

```python
from fastapi import FastAPI
from netguard import NetGuard, NetGuardConfig
from netguard.integrations.fastapi import setup_netguard

app = FastAPI()
# `secrets` below represents the secret manager provided by your host.
config = NetGuardConfig(
    project_id="my-app",
    auth_username="admin",
    auth_password=secrets.get("netguard-dashboard-password"),
)
guard = NetGuard(config=config)
setup_netguard(app, guard)
```

The authenticated dashboard is mounted at `/netguard/`. For a single
application, the embedded dashboard is the simplest option. To aggregate
several applications, run `netguard serve` as a separate dashboard service and
configure each application with `dashboard_mode="separate"` and its
`dashboard_url`.

Keep dashboard and email provider credentials in your deployment platform's
secret manager. Do not commit credentials to source control. Configure NetGuard
directly with `NetGuardConfig` or use the `NETGUARD_*` settings described in
the [full project guide](nids-project/README.md).

Email can be delivered through SMTP or the Resend HTTPS API. For hosts that
block SMTP, select the Resend provider with `NETGUARD_EMAIL_PROVIDER=resend`,
`NETGUARD_RESEND_API_KEY`, `NETGUARD_RESEND_FROM`, and `NETGUARD_ALERT_EMAIL`.
FastAPI starts and stops the weekly digest scheduler with the app lifecycle
when the selected provider is configured. Run one scheduler process per app to
avoid duplicate digests in multi-worker deployments. Other frameworks should
manage it from their own lifecycle or use one external scheduler.

## Optional integrations

- `netguard-threat-monitor[web]`: FastAPI, Django, and ASGI server dependencies.
- `netguard-threat-monitor[flask]`: dependency for the separate legacy Flask extension.
- `netguard-threat-monitor[train]`: model training and offline-analysis dependencies.

NetGuard is distributed under the MIT License; see [LICENSE](LICENSE).

## Model and dataset acknowledgement

The bundled model is associated with CICIDS2017-style flow data. The dataset
itself is not included in this package. The Canadian Institute for
Cybersecurity asks users of CICIDS2017 to cite the dataset paper:

Iman Sharafaldin, Arash Habibi Lashkari, and Ali A. Ghorbani, “Toward
Generating a New Intrusion Detection Dataset and Intrusion Traffic
Characterization,” ICISSP, 2018. See the [CIC-IDS2017 dataset page](https://www.unb.ca/cic/datasets/ids-2017.html).

The MIT license covers NetGuard's project files; it does not replace any
separate terms that may apply to third-party material or model artifacts.
