---
sidebar_label: Security model
toc_max_heading_level: 3
doc_id: 3e8c1f47-b29d-4a06-8d5e-c1f9e2730b8a
description: >-
  Security guarantees nullplatform provides for the agent running in your
  infrastructure, including transport, execution scoping, and credential handling.
keywords:
  - agent
  - security
  - nullplatform
  - TLS
  - WebSocket
  - execution scoping
  - credentials
---

# Agent security model

The nullplatform agent runs inside your own infrastructure. This page covers the security guarantees nullplatform provides for the agent and what remains under your control as the operator.

## How it connects

```mermaid
flowchart LR
    A["**Customer infrastructure**<br/>Agent lives in your infrastructure.<br/>Initiates a WebSocket connection<br/>toward nullplatform."]
    B["**nullplatform**<br/>Receives the connection and<br/>delivers events to the agent."]
    C["**Customer local execution**<br/>The agent executes events in<br/>your environment: infrastructure,<br/>applications, internal services."]

    A -- "WebSocket TLS (outbound)" --> B
    B -- "events" --> C

    classDef customer fill:#eef3fb,stroke:#274a86,color:#0b1e3f,stroke-width:1.5px;
    classDef np       fill:#e6faf4,stroke:#00b894,color:#0b1e3f,stroke-width:1.5px;
    class A,C customer;
    class B np;

    linkStyle 0 stroke:#0b1e3f,stroke-width:2.5px;
    linkStyle 1 stroke:#00b894,stroke-width:2px;
```

> 🔒 Nullplatform never initiates a connection into your environment — traffic flows outbound only, from your infrastructure to the platform.

## Security guarantees

- **Encrypted and authenticated connection:** All communication between the agent and the platform runs over WebSocket TLS. The agent authenticates before receiving any instruction.

- **No access to customer credentials:** Nullplatform doesn't store or access your API keys or secrets. Credentials live entirely in your environment.

- **Execution scoped by design:** The agent operates with a declared set of capabilities. Commands can only run from explicitly allowed paths. Path traversal, symlink attacks, and arbitrary execution are blocked at the agent code level.

- **Repository-bound execution:** The agent configuration includes a fixed allowlist of repositories and branches. This list is immutable after the agent starts, so all executions happen exclusively from pre-approved code.

- **Authenticated and authorized commands:** All commands sent to the agent API are authenticated and authorized by nullplatform over HTTPS. The agent receives structured commands and runs them only within the configured repositories, with protections against subshell injection and path manipulation.

- **IAM-bounded execution:** The agent runs with the IAM roles you assign to it. It can only access the cloud resources those roles explicitly permit, which limits the blast radius of any executed action.

## Auditability and control

You have full visibility into every action the agent takes within your infrastructure: commands executed, scripts run, and services accessed.

Certain actions, such as deployment executions, can be gated by approval workflows. The agent won't proceed until the required approval is granted, giving teams an additional governance layer over sensitive operations.

> 💡 **Tip:** You can deploy multiple agents simultaneously, one per namespace, application, or team, for granular access control and per-environment isolation.

## Responsibilities at a glance

Nullplatform handles security of the platform. You handle security in your infrastructure.

<div className="resp-model">
<div className="rm-card">
<div className="rm-legend">
  <span><span className="rm-swatch rm-np-sw"></span><img src="/img/logo-wordmark.svg" className="rm-legend-logo" alt="nullplatform" /> guarantees</span>
  <span><span className="rm-swatch rm-cust-sw"></span>You manage</span>
</div>
<div className="rm-row">
  <div className="rm-stage">
    <div className="rm-rail np-rail">
      <div className="rm-who"><img src="/img/logo-wordmark.svg" className="rm-who-logo" alt="nullplatform" /></div>
      <div className="rm-role">Responsibility for<br/>security <em>of</em> the agent</div>
    </div>
    <div className="rm-grid np-grid">
      <div className="rm-cell"><div className="rm-tag">Transport</div><div className="rm-text">TLS transport with agent authentication</div></div>
      <div className="rm-cell"><div className="rm-tag">Identity &amp; access</div><div className="rm-text">Command authentication and authorization over HTTPS</div></div>
      <div className="rm-cell"><div className="rm-tag">Secrets &amp; credentials</div><div className="rm-text">Zero retention of customer credentials</div></div>
      <div className="rm-cell"><div className="rm-tag">Execution boundary</div><div className="rm-text">Execution guardrails enforced in agent code</div></div>
      <div className="rm-cell"><div className="rm-tag">Source allowlist</div><div className="rm-text">Immutable repository allowlist at agent startup</div></div>
      <div className="rm-cell"><div className="rm-tag">Distribution</div><div className="rm-text">Versioned agent image via Docker Registry</div></div>
      <div className="rm-cell"><div className="rm-tag">Resilience</div><div className="rm-text">Reconnection with retry and backoff</div></div>
    </div>
  </div>
</div>
<div className="rm-row">
  <div className="rm-stage">
    <div className="rm-rail cust-rail">
      <div className="rm-who">You</div>
      <div className="rm-role">Responsibility for<br/>security <em>in</em> your infra</div>
    </div>
    <div className="rm-grid cust-grid">
      <div className="rm-cell"><div className="rm-tag">Identity &amp; access</div><div className="rm-text">IAM permissions following least-privilege</div></div>
      <div className="rm-cell"><div className="rm-tag">Secrets &amp; credentials</div><div className="rm-text">Secrets and API keys in your vault or Kubernetes Secrets</div></div>
      <div className="rm-cell"><div className="rm-tag">Rotation &amp; auditing</div><div className="rm-text">Credential rotation and access auditing</div></div>
      <div className="rm-cell"><div className="rm-tag">Observability</div><div className="rm-text">Audit logs and observability of agent actions</div></div>
    </div>
  </div>
</div>
</div>
</div>

## Next steps

- [Authenticate the agent](./authentication): create an API key and configure NRN-scoped permissions
- [Install the agent](./installation): deploy the agent with Helm and verify it's running