Metadata-Version: 2.4
Name: quasentra
Version: 0.1.0
Summary: Runtime authorization and approval enforcement for AI agents
Author: Quasentra
License-Expression: LicenseRef-Proprietary
Project-URL: Homepage, https://agent.gdprnest.com
Project-URL: Documentation, https://agent.gdprnest.com/documentation
Project-URL: Repository, https://github.com/Adnan-1234/Agent_Security
Project-URL: Issues, https://github.com/Adnan-1234/Agent_Security/issues
Keywords: ai-agents,authorization,langgraph,crewai,security
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: httpx<1,>=0.26
Provides-Extra: server
Requires-Dist: fastapi<1,>=0.109; extra == "server"
Requires-Dist: sqlalchemy<3,>=2.0; extra == "server"
Requires-Dist: aiosqlite<1,>=0.19; extra == "server"
Requires-Dist: pydantic<3,>=2.5; extra == "server"
Requires-Dist: pydantic-settings<3,>=2.1; extra == "server"
Requires-Dist: python-jose[cryptography]<4,>=3.3; extra == "server"
Requires-Dist: redis<6,>=5; extra == "server"
Provides-Extra: test
Requires-Dist: httpx<1,>=0.26; extra == "test"
Provides-Extra: langgraph
Requires-Dist: langchain<2,>=1.0; extra == "langgraph"
Requires-Dist: langgraph<2,>=1.0; extra == "langgraph"
Provides-Extra: crewai
Requires-Dist: crewai<2,>=1; extra == "crewai"
Provides-Extra: openai-agents
Requires-Dist: openai-agents<1,>=0.7; extra == "openai-agents"

# Quasentra

Quasentra is a framework-independent authorization and execution-security
platform for locally developed AI agents. Its security model assumes that an
agent may be manipulated or compromised and limits the actions it can execute.

## Python SDK

The first Quasentra SDK release is `0.1.0` (alpha). After the public PyPI release,
application developers install it with:

```bash
pip install quasentra==0.1.0
```

SDK contributors working from a repository checkout use:

```bash
pip install -e .
```

Configure once through environment variables:

```text
QUASENTRA_API_KEY=ask_live_...
QUASENTRA_URL=https://agent.gdprnest.com
```

Create one reusable security object, then secure an agent factory with a
Django-style decorator:

```python
from quasentra import Quasentra

security = Quasentra(
    api_key=os.environ["QUASENTRA_API_KEY"],
    base_url=os.environ.get("QUASENTRA_URL", "http://127.0.0.1:8080"),
)

@security.protect("support-agent")
def build_agent():
    return Agent(tools=[crm_customer_read, email_send])

agent = build_agent()
result = agent.invoke("Read customer 42")
```

The generic adapter supports agent objects whose `tools` attribute is a list of
plain synchronous or asynchronous Python callables. Unsupported objects fail
explicitly; they are never silently marked secure.

When an operation requires approval, the wrapper raises `ApprovalRequired` and
does not execute the tool. After an administrator approves the exact operation,
retry it through the context-local helper. The approval ID is not exposed to
the tool or its schema:

```python
try:
    agent.tools[0](amount=1000)
except ApprovalRequired as pending:
    # Present pending.approval_id to the administrator workflow.
    wait_for_admin_review(pending.approval_id)
    with security.resume(pending):
        agent.tools[0](amount=1000)
```

The server verifies the same tenant, agent, action and canonical arguments,
then consumes the approval once. A changed or replayed request is denied.

## Framework adapters

Install integrations in the agent application's environment, separate from the
Quasentra API server environment:

```powershell
pip install "quasentra[langgraph]"
pip install "quasentra[crewai]"
pip install "quasentra[openai-agents]"
```

Install only the adapter used by that application. CrewAI 1.15.17 currently
requires `openai<3`, while OpenAI Agents SDK 0.22.0 requires `openai>=3`; those
two framework versions cannot share one Python environment. This does not
affect separate CrewAI and OpenAI agent services.

Use `security.langgraph(...)`, `security.crewai(...)`, or
`security.openai_agent(...)`. CrewAI local `BaseTool` objects and OpenAI local
`FunctionTool` objects are intercepted before execution. OpenAI hosted tools are
rejected because their remote execution cannot be intercepted by local hooks.

## Gateway-enforced tools

For high-risk operations, call `security.execute(...)` or
`await security.aexecute(...)`. The API authorizes the exact operation and then
executes an administrator-installed connector; business credentials are loaded
from Vault and never enter the agent process. Built-in connectors support
administrator-allowlisted HTTPS routes, named PostgreSQL read-only queries, and
SMTP email with recipient-domain restrictions. Configure them using
`architecture/gateway-connectors.example.json` and set
`GATEWAY_CONNECTOR_CONFIG_FILE` to the mounted configuration path. API keys need
the `tool:execute` scope.

## Enforcement levels

- `Intercept`: SDK wrapper blocks supported tool hooks.
- `Enforce`: business credentials remain in the server-side tool gateway and
  the agent cannot directly reach the protected resource.
- `Isolate`: execution additionally uses an approved sandbox profile.

The decorator currently provides `Intercept`. Use `/api/v1/tools/execute` and
remove direct business credentials/network paths to obtain gateway enforcement.

Gateway execution requests require a unique, unpredictable `idempotency_key`
(16-100 safe characters). Reusing it never executes the connector twice; reusing
it with changed arguments returns a conflict. Connectors also have bounded
timeouts, baseline private-network URL blocking, safe exception responses, and
credential-aware output redaction. Connector-specific destination allowlists are
still required for URL-fetching integrations.

Untrusted code profiles are networkless and run as UID/GID 65532 with a
read-only root, all capabilities dropped, no-new-privileges, disabled IPC,
resource limits, digest-pinned images, administrator-approved mount roots, and
bounded output. Run `scripts/run_docker_sandbox_red_team.py` on a dedicated
Docker staging host to collect real isolation evidence.

## Database migrations

Production never calls `create_all()`. It refuses to start unless the database
is at the repository's Alembic head. Apply migrations before deployment:

```bash
alembic upgrade head
```

For a rollback rehearsal on an isolated backup/restored database:

```bash
alembic downgrade -1
alembic upgrade head
```

Do not blindly stamp an existing database. First compare its complete schema to
revision `0001`; stamping a structurally different database hides migration
drift. `scripts/run_postgres_migration_pilot.py` verifies upgrade and downgrade
against an ephemeral digest-pinned PostgreSQL 16 container.
Sandboxed execution requires Docker and an administrator-approved image; Docker
unavailability fails closed.

## LangGraph

LangGraph middleware must be installed when the agent is created; attaching it
to an already compiled graph is not a verified security boundary.

```python
from quasentra import Quasentra

security = Quasentra(api_key=os.environ["QUASENTRA_API_KEY"])
middleware = security.langgraph(
    agent_id="support-agent",
    name="Support Agent",
    tools=tools,
)

agent = create_agent(model=model, tools=tools, middleware=[middleware])
```

See `examples/langgraph_support_pilot.py` for the runnable pilot structure.

## Verification

```powershell
.\myenv\Scripts\python.exe -m unittest discover -s tests -p "test_*_unittest.py"
```

Architecture and current limitations are documented under `architecture/`.
The complete developer contract, framework compatibility matrix, typed errors,
and release workflow are in `architecture/SDK.md`.
## Automated-agent traffic

The backend is FastAPI. Decision traffic has distributed Redis tenant/agent/burst
quotas plus per-worker concurrency backpressure. Limits are configured through
`AGENT_RATE_LIMIT_PER_MINUTE`, `AGENT_BURST_PER_SECOND`,
`TENANT_RATE_LIMIT_PER_MINUTE`, and `DECISION_MAX_IN_FLIGHT_PER_WORKER`.
Clients must honor `429`/`503` and `Retry-After`; see
`architecture/SCALING.md` for defaults, evidence, and deployment guidance.

The Python SDK applies bounded retry/backoff while reusing the original request
ID and nonce. Configure `max_retries`, `retry_base_seconds`, and
`retry_max_seconds` through `quasentra.configure(...)`. Close its pooled
client during graceful shutdown when managing `SecurityClient` directly.

## Gateway secrets

Production gateway credentials are retrieved from Vault KV v2 using metadata-only
tenant/agent/action bindings. Secret values are never accepted by management APIs
or stored in the application database. See `architecture/SECRETS.md`.
