---
order: 2
summary: Default deny, allow rules about identities, and why every connection is authorised
  twice.
title: Policy
path: concepts/policy
status: published
---

# Policy

Policy decides whether one identity may open a connection to one service.
Nothing is reachable until a rule says it is.

## Default deny

An empty policy set means no connection succeeds. There is no implicit
"same realm can talk to itself" and no "allow all within the tenant" default.
If you want two things to talk, write that down.

## The shape of a rule

```
allow  from <identity selector>  to <service>  ports <list>
```

```bash
proxility policy allow \
  --from 'prox://acme/prod/*' \
  --to payments.prod.acme \
  --ports 8443
```

| Field | Meaning |
|---|---|
| `from` | One identity, or a selector with a trailing `*` wildcard on the name |
| `to` | A published service name |
| `ports` | Explicit port list. There is no "all ports" value |
| `description` | Free text. Write why, not what — the rule already says what |

Selectors wildcard only the **name** segment. `prox://acme/*/payments` is
rejected: crossing realms is a deliberate act, not a pattern match. To grant
cross-realm access, name the realm explicitly.

## Evaluated twice

Every connection is authorised at **both** ends:

1. The **origin** connector checks the rule before it will open a session.
2. The **destination** connector checks the same rule before it will connect
   to the local target.

This is deliberate redundancy. A compromised origin connector that skips its
own check still faces the destination's check, and the destination trusts the
peer identity from the mutually authenticated handshake rather than anything
the origin claims about itself.

The edge does **not** evaluate policy. It routes ciphertext between connectors
it has authenticated. Policy lives with the endpoints that enforce it.

## Deny reasons

A denied attempt produces one of these, and it is always specific:

| Reason | Meaning |
|---|---|
| `no_matching_rule` | Nothing allows this pair. The common case |
| `port_not_allowed` | A rule matches the identities but not the port |
| `service_unknown` | The name does not resolve to a published service |
| `identity_expired` | The peer's certificate has aged out and not renewed |
| `identity_revoked` | The peer was revoked |
| `connector_offline` | The destination connector is not attached to any edge |

See [Denied by policy](/docs/proxility/troubleshooting/denied-by-policy) for
working through these.

## Change control

Policy changes are versioned. Each change records the author, the time and the
diff, and the whole set can be read back as a single document:

```bash
proxility policy show --format yaml > policy.yaml   # review, commit to git
proxility policy apply policy.yaml --dry-run        # shows what would change
proxility policy apply policy.yaml
```

Teams that care about audit should keep `policy.yaml` in version control and
apply from CI. `--dry-run` prints added and removed rules and exits non-zero if
anything would change, which makes a useful drift check.

## Designing a policy model

Two habits that age well:

- **Name services narrowly.** One service per port per purpose. A service
  called `database` on three ports becomes a rule you cannot reason about.
- **Prefer attested workload identity over connector identity.** A rule that
  says `prox://acme/prod/aws-prod` grants the whole network behind that
  connector. A rule that says `prox://acme/prod/api-server` grants one
  workload. See [Identity](/docs/proxility/concepts/identity).
