diff --git a/.github/FUNDING.yml b/.github/FUNDING.yml index 31e8d02..2dcd93e 100644 --- a/.github/FUNDING.yml +++ b/.github/FUNDING.yml @@ -1,6 +1,6 @@ # These are supported funding model platforms -github: rennf93 +github: Guard-Core # patreon: # Replace with a single Patreon username # open_collective: # Replace with a single Open Collective username # ko_fi: # Replace with a single Ko-fi username diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml index 90adf2b..344996c 100644 --- a/.github/ISSUE_TEMPLATE/config.yml +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -1,10 +1,10 @@ blank_issues_enabled: false contact_links: - name: Guard Agent Documentation - url: https://rennf93.github.io/guard-agent/ + url: https://guard-core.github.io/guard-agent/ about: Check the documentation for usage information and tutorials - name: Usage Questions - url: https://github.com/rennf93/guard-agent/discussions + url: https://github.com/Guard-Core/guard-agent/discussions about: Please ask and answer questions in GitHub Discussions - name: Discord url: https://discord.gg/ZW7ZJbjMkK diff --git a/.github/workflows/container-release.yml b/.github/workflows/container-release.yml new file mode 100644 index 0000000..e40ca99 --- /dev/null +++ b/.github/workflows/container-release.yml @@ -0,0 +1,57 @@ +name: Publish Containerized Demo + +on: + release: + types: [created] + push: + branches: + - master + paths: + - 'examples/**' + - 'guard_agent/**' + - 'pyproject.toml' + - '.github/workflows/container-release.yml' + workflow_dispatch: + +jobs: + publish-container: + runs-on: ubuntu-latest + permissions: + packages: write + contents: read + + steps: + - name: Checkout code + uses: actions/checkout@v7 + + - name: Set version tag + id: set_version + run: | + if [[ "${{ github.event_name }}" == "release" ]]; then + echo "VERSION=${{ github.event.release.tag_name }}" >> $GITHUB_ENV + echo "IS_RELEASE=true" >> $GITHUB_ENV + else + echo "VERSION=latest" >> $GITHUB_ENV + echo "IS_RELEASE=false" >> $GITHUB_ENV + fi + + - name: Log in to GHCR + uses: docker/login-action@v4 + with: + registry: ghcr.io + username: ${{ github.actor }} + password: ${{ secrets.GITHUB_TOKEN }} + + - name: Build image + run: | + docker build -f examples/demo_app/Dockerfile -t guard-agent-demo . + + - name: Tag and Push to GHCR + run: | + docker tag guard-agent-demo ghcr.io/guard-core/guard-agent:latest + docker push ghcr.io/guard-core/guard-agent:latest + + if [[ "${{ env.IS_RELEASE }}" == "true" ]]; then + docker tag guard-agent-demo ghcr.io/guard-core/guard-agent:${{ env.VERSION }} + docker push ghcr.io/guard-core/guard-agent:${{ env.VERSION }} + fi diff --git a/AGENTS.md b/AGENTS.md index c39a930..1a5a3d5 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -210,10 +210,10 @@ uv run pytest tests/test_buffer.py::test_name -v ## Related Projects -- **guard-core** - Framework-agnostic security engine (telemetry models live here too): -- **fastapi-guard** - FastAPI/Starlette adapter: -- **flaskapi-guard** - Flask extension adapter: -- **djapi-guard** - Django middleware adapter: -- **tornadoapi-guard** - Tornado handler/middleware adapter: -- **guard-core-mcp** - MCP server for config validation and docs search: -- **guard-core-app** - SaaS platform this agent reports to (ingestion API, dashboard, playground): +- **guard-core** - Framework-agnostic security engine (telemetry models live here too): +- **fastapi-guard** - FastAPI/Starlette adapter: +- **flaskapi-guard** - Flask extension adapter: +- **djapi-guard** - Django middleware adapter: +- **tornadoapi-guard** - Tornado handler/middleware adapter: +- **guard-core-mcp** - MCP server for config validation and docs search: +- **guard-core-app** - SaaS platform this agent reports to (ingestion API, dashboard, playground): diff --git a/CLAUDE.md b/CLAUDE.md index c39a930..1a5a3d5 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -210,10 +210,10 @@ uv run pytest tests/test_buffer.py::test_name -v ## Related Projects -- **guard-core** - Framework-agnostic security engine (telemetry models live here too): -- **fastapi-guard** - FastAPI/Starlette adapter: -- **flaskapi-guard** - Flask extension adapter: -- **djapi-guard** - Django middleware adapter: -- **tornadoapi-guard** - Tornado handler/middleware adapter: -- **guard-core-mcp** - MCP server for config validation and docs search: -- **guard-core-app** - SaaS platform this agent reports to (ingestion API, dashboard, playground): +- **guard-core** - Framework-agnostic security engine (telemetry models live here too): +- **fastapi-guard** - FastAPI/Starlette adapter: +- **flaskapi-guard** - Flask extension adapter: +- **djapi-guard** - Django middleware adapter: +- **tornadoapi-guard** - Tornado handler/middleware adapter: +- **guard-core-mcp** - MCP server for config validation and docs search: +- **guard-core-app** - SaaS platform this agent reports to (ingestion API, dashboard, playground): diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index a733ba2..4153dad 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -76,7 +76,7 @@ Enforcement Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at -@rennf93. +contact@guard-core.com. All complaints will be reviewed and investigated promptly and fairly. All community leaders are obligated to respect the privacy and security of the diff --git a/README.md b/README.md index 521d844..c4f5648 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@

- - Guard Agent + + Guard Agent

@@ -14,28 +14,31 @@ PyPiVersion - - Release + + Release License - - CI + + CI - - CodeQL + + CodeQL

- - PagesBuildDeployment + + PagesBuildDeployment - - DocsUpdate + + DocsUpdate - last-commit + + Docs + + last-commit

@@ -48,7 +51,7 @@

Website · - Docs · + Docs · Playground · Dashboard · Discord @@ -69,7 +72,7 @@ Documentation & Platform ======================== - 🌐 **[guard-core.com](https://guard-core.com)** — marketing site & product overview -- 📚 **[Documentation](https://rennf93.github.io/guard-agent/latest/)** — full technical documentation +- 📚 **[Documentation](https://guard-core.github.io/guard-agent/latest/)** — full technical documentation - 🎮 **[Playground](https://playground.guard-core.com)** — try the Guard stack in-browser, no install required - 📊 **[Dashboard](https://app.guard-core.com)** — real-time security events, metrics, and dynamic rules for your projects - 💬 **[Discord](https://discord.gg/ZW7ZJbjMkK)** — community & maintainer support @@ -85,24 +88,24 @@ Guard Agent is the Python telemetry agent for the Guard ecosystem. It pairs with | Package | Role | PyPI | |---|---|---| -| [guard-core](https://github.com/rennf93/guard-core) | Framework-agnostic security engine | [![PyPI](https://img.shields.io/pypi/v/guard-core)](https://pypi.org/project/guard-core/) | -| [guard-agent](https://github.com/rennf93/guard-agent) | Telemetry agent (this package) | [![PyPI](https://img.shields.io/pypi/v/guard-agent)](https://pypi.org/project/guard-agent/) | -| [fastapi-guard](https://github.com/rennf93/fastapi-guard) | FastAPI / Starlette adapter | [![PyPI](https://img.shields.io/pypi/v/fastapi-guard)](https://pypi.org/project/fastapi-guard/) | -| [flaskapi-guard](https://github.com/rennf93/flaskapi-guard) | Flask adapter | [![PyPI](https://img.shields.io/pypi/v/flaskapi-guard)](https://pypi.org/project/flaskapi-guard/) | -| [djapi-guard](https://github.com/rennf93/djapi-guard) | Django adapter | [![PyPI](https://img.shields.io/pypi/v/djapi-guard)](https://pypi.org/project/djapi-guard/) | -| [tornadoapi-guard](https://github.com/rennf93/tornadoapi-guard) | Tornado adapter | [![PyPI](https://img.shields.io/pypi/v/tornadoapi-guard)](https://pypi.org/project/tornadoapi-guard/) | +| [guard-core](https://github.com/Guard-Core/guard-core) | Framework-agnostic security engine | [![PyPI](https://img.shields.io/pypi/v/guard-core)](https://pypi.org/project/guard-core/) | +| [guard-agent](https://github.com/Guard-Core/guard-agent) | Telemetry agent (this package) | [![PyPI](https://img.shields.io/pypi/v/guard-agent)](https://pypi.org/project/guard-agent/) | +| [fastapi-guard](https://github.com/Guard-Core/fastapi-guard) | FastAPI / Starlette adapter | [![PyPI](https://img.shields.io/pypi/v/fastapi-guard)](https://pypi.org/project/fastapi-guard/) | +| [flaskapi-guard](https://github.com/Guard-Core/flaskapi-guard) | Flask adapter | [![PyPI](https://img.shields.io/pypi/v/flaskapi-guard)](https://pypi.org/project/flaskapi-guard/) | +| [djapi-guard](https://github.com/Guard-Core/djapi-guard) | Django adapter | [![PyPI](https://img.shields.io/pypi/v/djapi-guard)](https://pypi.org/project/djapi-guard/) | +| [tornadoapi-guard](https://github.com/Guard-Core/tornadoapi-guard) | Tornado adapter | [![PyPI](https://img.shields.io/pypi/v/tornadoapi-guard)](https://pypi.org/project/tornadoapi-guard/) | ### TypeScript / JavaScript -Published under the [`@guardcore`](https://www.npmjs.com/org/guardcore) npm scope. Source in the [guard-core-ts](https://github.com/rennf93/guard-core-ts) monorepo. **Production-ready.** +Published under the [`@guardcore`](https://www.npmjs.com/org/guardcore) npm scope. Source in the [guard-core-ts](https://github.com/Guard-Core/guard-core-ts) monorepo. **Production-ready.** | Package | Role | npm | |---|---|---| -| [@guardcore/core](https://github.com/rennf93/guard-core-ts/tree/master/packages/core) | Core engine | [![npm](https://img.shields.io/npm/v/%40guardcore%2Fcore)](https://www.npmjs.com/package/@guardcore/core) | -| [@guardcore/express](https://github.com/rennf93/guard-core-ts/tree/master/packages/express) | Express adapter | [![npm](https://img.shields.io/npm/v/%40guardcore%2Fexpress)](https://www.npmjs.com/package/@guardcore/express) | -| [@guardcore/nestjs](https://github.com/rennf93/guard-core-ts/tree/master/packages/nestjs) | NestJS adapter | [![npm](https://img.shields.io/npm/v/%40guardcore%2Fnestjs)](https://www.npmjs.com/package/@guardcore/nestjs) | -| [@guardcore/fastify](https://github.com/rennf93/guard-core-ts/tree/master/packages/fastify) | Fastify adapter | [![npm](https://img.shields.io/npm/v/%40guardcore%2Ffastify)](https://www.npmjs.com/package/@guardcore/fastify) | -| [@guardcore/hono](https://github.com/rennf93/guard-core-ts/tree/master/packages/hono) | Hono adapter | [![npm](https://img.shields.io/npm/v/%40guardcore%2Fhono)](https://www.npmjs.com/package/@guardcore/hono) | +| [@guardcore/core](https://github.com/Guard-Core/guard-core-ts/tree/master/packages/core) | Core engine | [![npm](https://img.shields.io/npm/v/%40guardcore%2Fcore)](https://www.npmjs.com/package/@guardcore/core) | +| [@guardcore/express](https://github.com/Guard-Core/guard-core-ts/tree/master/packages/express) | Express adapter | [![npm](https://img.shields.io/npm/v/%40guardcore%2Fexpress)](https://www.npmjs.com/package/@guardcore/express) | +| [@guardcore/nestjs](https://github.com/Guard-Core/guard-core-ts/tree/master/packages/nestjs) | NestJS adapter | [![npm](https://img.shields.io/npm/v/%40guardcore%2Fnestjs)](https://www.npmjs.com/package/@guardcore/nestjs) | +| [@guardcore/fastify](https://github.com/Guard-Core/guard-core-ts/tree/master/packages/fastify) | Fastify adapter | [![npm](https://img.shields.io/npm/v/%40guardcore%2Ffastify)](https://www.npmjs.com/package/@guardcore/fastify) | +| [@guardcore/hono](https://github.com/Guard-Core/guard-core-ts/tree/master/packages/hono) | Hono adapter | [![npm](https://img.shields.io/npm/v/%40guardcore%2Fhono)](https://www.npmjs.com/package/@guardcore/hono) | ### Rust @@ -110,17 +113,17 @@ Published on crates.io. **🚧 Placeholder crates — implementation in progress | Package | Role | crates.io | |---|---|---| -| [guard-core](https://github.com/rennf93/guard-core-rs) | Core engine | [![crates.io](https://img.shields.io/crates/v/guard-core)](https://crates.io/crates/guard-core) | -| [actix-guard-rs](https://github.com/rennf93/actix-guard-rs) | Actix adapter | [![crates.io](https://img.shields.io/crates/v/actix-guard-rs)](https://crates.io/crates/actix-guard-rs) | -| [axum-guard-rs](https://github.com/rennf93/axum-guard-rs) | Axum adapter | [![crates.io](https://img.shields.io/crates/v/axum-guard-rs)](https://crates.io/crates/axum-guard-rs) | -| [rocket-guard-rs](https://github.com/rennf93/rocket-guard-rs) | Rocket adapter | [![crates.io](https://img.shields.io/crates/v/rocket-guard-rs)](https://crates.io/crates/rocket-guard-rs) | -| [tower-guard-rs](https://github.com/rennf93/tower-guard-rs) | Tower adapter | [![crates.io](https://img.shields.io/crates/v/tower-guard-rs)](https://crates.io/crates/tower-guard-rs) | +| [guard-core](https://github.com/Guard-Core/guard-core-rs) | Core engine | [![crates.io](https://img.shields.io/crates/v/guard-core)](https://crates.io/crates/guard-core) | +| [actix-guard-rs](https://github.com/Guard-Core/actix-guard-rs) | Actix adapter | [![crates.io](https://img.shields.io/crates/v/actix-guard-rs)](https://crates.io/crates/actix-guard-rs) | +| [axum-guard-rs](https://github.com/Guard-Core/axum-guard-rs) | Axum adapter | [![crates.io](https://img.shields.io/crates/v/axum-guard-rs)](https://crates.io/crates/axum-guard-rs) | +| [rocket-guard-rs](https://github.com/Guard-Core/rocket-guard-rs) | Rocket adapter | [![crates.io](https://img.shields.io/crates/v/rocket-guard-rs)](https://crates.io/crates/rocket-guard-rs) | +| [tower-guard-rs](https://github.com/Guard-Core/tower-guard-rs) | Tower adapter | [![crates.io](https://img.shields.io/crates/v/tower-guard-rs)](https://crates.io/crates/tower-guard-rs) | ### AI Coding Agents | Package | Role | PyPI | |---|---|---| -| [guard-core-mcp](https://github.com/rennf93/guard-core-mcp) | MCP server — config validation, docs search, detection sandbox | [![PyPI](https://img.shields.io/pypi/v/guard-core-mcp)](https://pypi.org/project/guard-core-mcp/) | +| [guard-core-mcp](https://github.com/Guard-Core/guard-core-mcp) | MCP server — config validation, docs search, detection sandbox | [![PyPI](https://img.shields.io/pypi/v/guard-core-mcp)](https://pypi.org/project/guard-core-mcp/) | An MCP server that answers questions about Guard Agent from the version **installed in your project**, rather than from a model's memory of it. It validates a config against the real `AgentConfig` model — catching typos pydantic would otherwise ignore silently — looks up any field's type, default and description, and searches the bundled docs for all three Python packages. @@ -222,7 +225,7 @@ async def root() -> dict[str, str]: return {"message": "Hello World"} ``` -Flask is synchronous and handles start/stop internally; Tornado uses `await security_middleware.initialize()` / `reset()`; Django wires the middleware via settings. See [docs/adapters](https://rennf93.github.io/guard-agent/latest/adapters/fastapi/) for the canonical pattern per framework. +Flask is synchronous and handles start/stop internally; Tornado uses `await security_middleware.initialize()` / `reset()`; Django wires the middleware via settings. See [docs/adapters](https://guard-core.github.io/guard-agent/latest/adapters/fastapi/) for the canonical pattern per framework. With `enable_agent=True`, the agent automatically: @@ -334,7 +337,7 @@ This project is licensed under the MIT License. See the [LICENSE](LICENSE) file Author ------ -Renzo Franceschini - [rennf93@users.noreply.github.com](mailto:rennf93@users.noreply.github.com) +Renzo Franceschini - [contact@guard-core.com](mailto:contact@guard-core.com) --- diff --git a/SECURITY.md b/SECURITY.md index e475173..ac43aea 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -16,12 +16,12 @@ We take the security of Guard Agent seriously. If you believe you've found a sec 1. **Do not disclose the vulnerability publicly** until it has been addressed by the maintainers. 2. **Report the vulnerability through GitHub's security advisory feature**: - - Go to the [Security tab](https://github.com/rennf93/guard-agent/security/advisories) of the Guard Agent repository + - Go to the [Security tab](https://github.com/Guard-Core/guard-agent/security/advisories) of the Guard Agent repository - Click on "New draft security advisory" - Fill in the details of the vulnerability - Submit the advisory - Alternatively, you can report vulnerabilities through [GitHub's private vulnerability reporting feature](https://github.com/rennf93/guard-agent/security/advisories/new). + Alternatively, you can report vulnerabilities through [GitHub's private vulnerability reporting feature](https://github.com/Guard-Core/guard-agent/security/advisories/new). 3. Include the following information in your report: - A description of the vulnerability and its potential impact diff --git a/context7.json b/context7.json index 39f4b4d..00979bf 100644 --- a/context7.json +++ b/context7.json @@ -1,4 +1,4 @@ { - "url": "https://context7.com/rennf93/fastapi-guard-agent", + "url": "https://context7.com/Guard-Core/guard-agent", "public_key": "pk_Oa6yPCPtMpHNca5y8otCc" } diff --git a/docs/adapters/django.md b/docs/adapters/django.md index 6a9b614..1024f44 100644 --- a/docs/adapters/django.md +++ b/docs/adapters/django.md @@ -86,4 +86,4 @@ urlpatterns = [path("", views.root)] ## Related -- [`djapi-guard` on GitHub](https://github.com/rennf93/djangoapi-guard) +- [`djapi-guard` on GitHub](https://github.com/Guard-Core/djangoapi-guard) diff --git a/docs/adapters/fastapi.md b/docs/adapters/fastapi.md index 7890876..f8e0038 100644 --- a/docs/adapters/fastapi.md +++ b/docs/adapters/fastapi.md @@ -91,7 +91,7 @@ You don't see any of this in your code, and you don't need to. ## When you need the full guide -For the decision tree across all three integration paths (standalone / SaaS / encrypted SaaS), env-var conventions, common pitfalls (nginx body limits, key/api-key pairing, circuit-breaker behavior), see the canonical [**fastapi-guard Integration Guide**](https://rennf93.github.io/fastapi-guard/latest/tutorial/integration/). +For the decision tree across all three integration paths (standalone / SaaS / encrypted SaaS), env-var conventions, common pitfalls (nginx body limits, key/api-key pairing, circuit-breaker behavior), see the canonical [**fastapi-guard Integration Guide**](https://guard-core.github.io/fastapi-guard/latest/tutorial/integration/). ## Dashboard & Playground @@ -100,6 +100,6 @@ For the decision tree across all three integration paths (standalone / SaaS / en ## Related -- [`fastapi-guard` on GitHub](https://github.com/rennf93/fastapi-guard) -- [`fastapi-guard` integration guide](https://rennf93.github.io/fastapi-guard/latest/tutorial/integration/) — full decision tree + pitfalls -- [Canonical full example](https://github.com/rennf93/guard-core-app/blob/master/examples/app.py) in `guard-core-app` +- [`fastapi-guard` on GitHub](https://github.com/Guard-Core/fastapi-guard) +- [`fastapi-guard` integration guide](https://guard-core.github.io/fastapi-guard/latest/tutorial/integration/) — full decision tree + pitfalls +- [Canonical full example](https://github.com/Guard-Core/guard-core-app/blob/master/examples/app.py) in `guard-core-app` diff --git a/docs/adapters/flask.md b/docs/adapters/flask.md index fe74b71..66fc9fb 100644 --- a/docs/adapters/flask.md +++ b/docs/adapters/flask.md @@ -94,4 +94,4 @@ def create_app() -> Flask: ## Related -- [`flaskapi-guard` on GitHub](https://github.com/rennf93/flaskapi-guard) +- [`flaskapi-guard` on GitHub](https://github.com/Guard-Core/flaskapi-guard) diff --git a/docs/adapters/tornado.md b/docs/adapters/tornado.md index de7431a..abba55d 100644 --- a/docs/adapters/tornado.md +++ b/docs/adapters/tornado.md @@ -1,6 +1,6 @@ # Tornado Adapter — `tornadoapi-guard` -Guard Agent integrates with Tornado through the [`tornadoapi-guard`](https://github.com/rennf93/tornadoapi-guard) middleware. Because Tornado is fully async, the agent's lifecycle is driven by `await security_middleware.initialize()` (starts the agent) and `await security_middleware.reset()` (stops it). +Guard Agent integrates with Tornado through the [`tornadoapi-guard`](https://github.com/Guard-Core/tornadoapi-guard) middleware. Because Tornado is fully async, the agent's lifecycle is driven by `await security_middleware.initialize()` (starts the agent) and `await security_middleware.reset()` (stops it). !!! warning "Adapter not yet on PyPI" `tornadoapi-guard` 1.0.0 has not been published to PyPI at the time of writing. Install from source during the pre-release window, or wait for the first published release. @@ -8,19 +8,19 @@ Guard Agent integrates with Tornado through the [`tornadoapi-guard`](https://git ## Install (from source, pre-release) ```bash -uv pip install "git+https://github.com/rennf93/tornadoapi-guard.git" +uv pip install "git+https://github.com/Guard-Core/tornadoapi-guard.git" uv add guard-agent ``` Alternatives: ```bash -poetry add "git+https://github.com/rennf93/tornadoapi-guard.git" +poetry add "git+https://github.com/Guard-Core/tornadoapi-guard.git" poetry add guard-agent ``` ```bash -pip install "git+https://github.com/rennf93/tornadoapi-guard.git" +pip install "git+https://github.com/Guard-Core/tornadoapi-guard.git" pip install guard-agent ``` @@ -111,4 +111,4 @@ if __name__ == "__main__": ## Related -- [`tornadoapi-guard` on GitHub](https://github.com/rennf93/tornadoapi-guard) +- [`tornadoapi-guard` on GitHub](https://github.com/Guard-Core/tornadoapi-guard) diff --git a/docs/index.md b/docs/index.md index ef2d23b..7b3f6b2 100644 --- a/docs/index.md +++ b/docs/index.md @@ -7,8 +7,8 @@ keywords: fastapi, flask, django, tornado, security, middleware, telemetry, moni # Guard Agent

- - Guard Agent + + Guard Agent

@@ -23,28 +23,31 @@ keywords: fastapi, flask, django, tornado, security, middleware, telemetry, moni PyPiVersion - - Release + + Release License - - CI + + CI - - CodeQL + + CodeQL

- - PagesBuildDeployment + + PagesBuildDeployment - - DocsUpdate + + DocsUpdate - last-commit + + Docs + + last-commit

@@ -195,7 +198,7 @@ app.add_middleware(SecurityMiddleware, config=config) ### Advanced Usage Pattern !!! warning "Do not use this pattern with fastapi-guard" - The snippet below uses `guard_agent()` directly. If your app already uses `fastapi-guard`'s `SecurityMiddleware`, **do not** also call `guard_agent()` from your module-level code. The factory dispatches to `SyncGuardAgentHandler` when called from sync context (module load) and `GuardAgentHandler` when called from async context (the middleware's init) — they are **separate singletons**, and only the middleware's instance receives the telemetry stream. For fastapi-guard users, configure `agent_*` fields on `SecurityConfig` instead. See the [fastapi-guard Integration Guide](https://rennf93.github.io/fastapi-guard/latest/tutorial/integration/). + The snippet below uses `guard_agent()` directly. If your app already uses `fastapi-guard`'s `SecurityMiddleware`, **do not** also call `guard_agent()` from your module-level code. The factory dispatches to `SyncGuardAgentHandler` when called from sync context (module load) and `GuardAgentHandler` when called from async context (the middleware's init) — they are **separate singletons**, and only the middleware's instance receives the telemetry stream. For fastapi-guard users, configure `agent_*` fields on `SecurityConfig` instead. See the [fastapi-guard Integration Guide](https://guard-core.github.io/fastapi-guard/latest/tutorial/integration/). For specialized use cases that *don't* go through a framework adapter — custom event reporting in a worker, direct agent embedding in a non-adapter system, or sync-only frameworks (Flask, Django) integrated with `SyncGuardAgentHandler`: diff --git a/docs/installation.md b/docs/installation.md index 46c47c3..d97df3f 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -111,7 +111,7 @@ pip-sync requirements.txt For contributors and advanced users requiring source access: ```bash -git clone https://github.com/rennf93/guard-agent.git +git clone https://github.com/Guard-Core/guard-agent.git cd guard-agent uv sync --extra dev ``` diff --git a/docs/robots.txt b/docs/robots.txt index 349a421..49f542f 100644 --- a/docs/robots.txt +++ b/docs/robots.txt @@ -1,3 +1,3 @@ User-agent: * Allow: / -Sitemap: https://rennf93.github.io/guard-agent/sitemap.xml \ No newline at end of file +Sitemap: https://guard-core.github.io/guard-agent/sitemap.xml \ No newline at end of file diff --git a/examples/demo_app/Dockerfile b/examples/demo_app/Dockerfile new file mode 100644 index 0000000..0b9fd0c --- /dev/null +++ b/examples/demo_app/Dockerfile @@ -0,0 +1,39 @@ +FROM python:3.12-slim AS builder + +COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv + +WORKDIR /build + +COPY pyproject.toml README.md ./ +COPY guard_agent/ guard_agent/ + +RUN uv venv /app/.venv && \ + uv pip install --python /app/.venv/bin/python /build && \ + uv pip install --python /app/.venv/bin/python fastapi uvicorn + +FROM python:3.12-slim + +RUN groupadd --system guard && \ + useradd --system --gid guard --create-home guard + +WORKDIR /app + +COPY --from=builder --chown=guard:guard /app/.venv /app/.venv +COPY --chown=guard:guard examples/demo_app/main.py /app/main.py + +LABEL org.opencontainers.image.title="guard-agent demo" \ + org.opencontainers.image.description="Containerized Guard Agent demo: a FastAPI app streaming security telemetry to a Guard Core ingestion endpoint" \ + org.opencontainers.image.source="https://github.com/Guard-Core/guard-agent" \ + org.opencontainers.image.licenses="MIT" + +ENV PATH="/app/.venv/bin:$PATH" \ + PYTHONUNBUFFERED=1 \ + PYTHONDONTWRITEBYTECODE=1 \ + GUARD_AGENT_ENDPOINT=https://api.guard-core.com \ + GUARD_AGENT_PROJECT_ID=demo-project + +USER guard + +EXPOSE 8000 + +CMD ["uvicorn", "--host", "0.0.0.0", "--port", "8000", "main:app"] diff --git a/examples/demo_app/main.py b/examples/demo_app/main.py new file mode 100644 index 0000000..7f566de --- /dev/null +++ b/examples/demo_app/main.py @@ -0,0 +1,72 @@ +import os +from collections.abc import AsyncIterator +from contextlib import asynccontextmanager + +from fastapi import FastAPI + +from guard_agent import ( + AgentConfig, + GuardAgentHandler, + SecurityEvent, + get_current_timestamp, +) + +AGENT_ENDPOINT = os.getenv("GUARD_AGENT_ENDPOINT", "https://api.guard-core.com") +AGENT_API_KEY = os.getenv("GUARD_AGENT_API_KEY", "demo-api-key-12345") +AGENT_PROJECT_ID = os.getenv("GUARD_AGENT_PROJECT_ID", "demo-project") + + +def build_test_event() -> SecurityEvent: + return SecurityEvent( + timestamp=get_current_timestamp(), + event_type="custom_request_check", + ip_address="192.168.1.100", + action_taken="logged", + reason="Guard Agent demo container test event", + endpoint="/demo/test-event", + method="POST", + metadata={"source": "guard-agent-demo-container"}, + ) + + +agent_config = AgentConfig( + api_key=AGENT_API_KEY, + project_id=AGENT_PROJECT_ID, + endpoint=AGENT_ENDPOINT, + buffer_size=10, + flush_interval=5, +) +agent = GuardAgentHandler(agent_config) + + +@asynccontextmanager +async def lifespan(app: FastAPI) -> AsyncIterator[None]: + await agent.start() + await agent.send_event(build_test_event()) + yield + await agent.stop() + + +app = FastAPI(title="Guard Agent Demo", lifespan=lifespan) + + +@app.get("/") +async def root() -> dict[str, str]: + return { + "service": "guard-agent-demo", + "endpoint": AGENT_ENDPOINT, + "project_id": AGENT_PROJECT_ID, + } + + +@app.get("/health") +async def health() -> dict[str, str]: + status = await agent.get_status() + return {"status": status.status} + + +@app.post("/events") +async def emit_test_event() -> dict[str, str]: + event = build_test_event() + await agent.send_event(event) + return {"emitted": event.event_type} diff --git a/guard_agent/.agents/skills/guard-agent/SKILL.md b/guard_agent/.agents/skills/guard-agent/SKILL.md index 997da20..576a618 100644 --- a/guard_agent/.agents/skills/guard-agent/SKILL.md +++ b/guard_agent/.agents/skills/guard-agent/SKILL.md @@ -101,10 +101,10 @@ See [the transport reference](references/transport.md) for the exact return sema ## Related Projects -* [guard-core](https://github.com/rennf93/guard-core): framework-agnostic security engine whose adapters ship telemetry through this agent. -* [fastapi-guard](https://github.com/rennf93/fastapi-guard): FastAPI/Starlette adapter. -* [flaskapi-guard](https://github.com/rennf93/flaskapi-guard): Flask extension adapter. -* [djapi-guard](https://github.com/rennf93/djapi-guard): Django middleware adapter. -* [tornadoapi-guard](https://github.com/rennf93/tornadoapi-guard): Tornado handler/middleware adapter. -* [guard-core-mcp](https://github.com/rennf93/guard-core-mcp): MCP server for config validation and docs search. -* [guard-core-app](https://github.com/rennf93/guard-core-app): SaaS platform this agent reports to. +* [guard-core](https://github.com/Guard-Core/guard-core): framework-agnostic security engine whose adapters ship telemetry through this agent. +* [fastapi-guard](https://github.com/Guard-Core/fastapi-guard): FastAPI/Starlette adapter. +* [flaskapi-guard](https://github.com/Guard-Core/flaskapi-guard): Flask extension adapter. +* [djapi-guard](https://github.com/Guard-Core/djapi-guard): Django middleware adapter. +* [tornadoapi-guard](https://github.com/Guard-Core/tornadoapi-guard): Tornado handler/middleware adapter. +* [guard-core-mcp](https://github.com/Guard-Core/guard-core-mcp): MCP server for config validation and docs search. +* [guard-core-app](https://github.com/Guard-Core/guard-core-app): SaaS platform this agent reports to. diff --git a/mkdocs.yml b/mkdocs.yml index 3d1e0f4..d49882c 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,8 +1,8 @@ site_name: Guard Agent site_description: Framework-agnostic telemetry and monitoring agent for the Guard security ecosystem (fastapi-guard, flaskapi-guard, djangoapi-guard, tornadoapi-guard). -site_url: https://rennf93.github.io/guard-agent/latest/ -repo_name: rennf93/guard-agent -repo_url: https://github.com/rennf93/guard-agent +site_url: https://guard-core.github.io/guard-agent/latest/ +repo_name: Guard-Core/guard-agent +repo_url: https://github.com/Guard-Core/guard-agent edit_uri: edit/master/docs/ theme: @@ -90,7 +90,7 @@ plugins: extra: social: - icon: fontawesome/brands/github - link: https://github.com/rennf93/guard-agent + link: https://github.com/Guard-Core/guard-agent name: GitHub - icon: fontawesome/brands/python link: https://pypi.org/project/guard-agent/ @@ -124,7 +124,7 @@ extra: data: 0 note: >- Thanks for your feedback! Help us improve by using our - issue tracker. + issue tracker. generator: false meta: @@ -135,7 +135,7 @@ extra: - property: og:description content: Framework-agnostic telemetry and monitoring agent for the Guard security ecosystem (fastapi-guard, flaskapi-guard, djangoapi-guard, tornadoapi-guard). - property: og:image - content: https://rennf93.github.io/guard-agent/assets/guard_agent_legend.svg + content: https://guard-core.github.io/guard-agent/assets/guard_agent_legend.svg - name: keywords content: fastapi, flask, django, tornado, security, middleware, python, telemetry, monitoring, ip control, rate limiting, penetration detection diff --git a/pyproject.toml b/pyproject.toml index 939e1a0..dd8560d 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -3,7 +3,7 @@ name = "guard-agent" version = "3.2.1" description = "Framework-agnostic telemetry and monitoring agent for the Guard security ecosystem (fastapi-guard, flaskapi-guard, djangoapi-guard, tornadoapi-guard)" authors = [ - {name = "Renzo Franceschini", email = "rennf93@users.noreply.github.com"} + {name = "Renzo Franceschini", email = "rennf93@guard-core.com"} ] readme = "README.md" license = "MIT" @@ -31,10 +31,10 @@ dependencies = [ [project.urls] Homepage = "https://guard-core.com" -Documentation = "https://rennf93.github.io/guard-agent/latest/" -Repository = "https://github.com/rennf93/guard-agent" -Changelog = "https://github.com/rennf93/guard-agent/blob/master/CHANGELOG.md" -"Bug Tracker" = "https://github.com/rennf93/guard-agent/issues" +Documentation = "https://guard-core.github.io/guard-agent/latest/" +Repository = "https://github.com/Guard-Core/guard-agent" +Changelog = "https://github.com/Guard-Core/guard-agent/blob/master/CHANGELOG.md" +"Bug Tracker" = "https://github.com/Guard-Core/guard-agent/issues" "Cloud Dashboard" = "https://app.guard-core.com" "Live Playground" = "https://playground.guard-core.com" diff --git a/shim/README.md b/shim/README.md index fad844c..52fb1f2 100644 --- a/shim/README.md +++ b/shim/README.md @@ -40,6 +40,6 @@ pip uninstall fastapi-guard-agent && pip install guard-agent - **Dashboard:** - **Playground:** - **New package on PyPI:** -- **Repository:** -- **Documentation:** -- **CHANGELOG (v2.0.0 rename notes):** +- **Repository:** +- **Documentation:** +- **CHANGELOG (v2.0.0 rename notes):** diff --git a/shim/pyproject.toml b/shim/pyproject.toml index de7f37f..d18ae07 100644 --- a/shim/pyproject.toml +++ b/shim/pyproject.toml @@ -3,7 +3,7 @@ name = "fastapi_guard_agent" version = "1.3.0" description = "Deprecated alias — the package has been renamed to guard-agent. Installing fastapi-guard-agent will transitively install guard-agent." authors = [ - {name = "Renzo Franceschini", email = "rennf93@users.noreply.github.com"} + {name = "Renzo Franceschini", email = "rennf93@guard-core.com"} ] readme = "README.md" license = {text = "MIT"} @@ -29,7 +29,7 @@ dependencies = [ [project.urls] Homepage = "https://guard-core.com" "Renamed To" = "https://pypi.org/project/guard-agent/" -Repository = "https://github.com/rennf93/guard-agent" +Repository = "https://github.com/Guard-Core/guard-agent" "Cloud Dashboard" = "https://app.guard-core.com" "Live Playground" = "https://playground.guard-core.com"