cloud-network-security

What this skill does

# Cloud Network Security

Manage network security policies for Elastic Cloud Serverless projects: IP filters to allowlist specific IPs or CIDRs,
and VPC filters (AWS PrivateLink) to restrict traffic to specific VPC endpoints.

> **Prerequisite:** This skill assumes the **cloud-setup** skill has already run — `EC_API_KEY` is set in the
> environment and the organization context is established. If `EC_API_KEY` is missing, instruct the agent to invoke
> **cloud-setup** first. Do NOT prompt the user for an API key directly.

For project creation and day-2 operations (including associating filters with projects), see **cloud-create-project**
and **cloud-manage-project**. For identity and access management (users, roles, API keys), see
**cloud-access-management**.

For detailed API endpoints and request schemas, see [references/api-reference.md](references/api-reference.md).

## Terminology

This skill uses **network security** as the umbrella term, aligned with the Elastic Cloud UI direction. The underlying
API uses **traffic filters** — you will see `traffic-filters` in endpoint paths and `traffic_filters` in JSON fields.
When a user or agent says "traffic filter," they mean the same thing as "network security policy." The two filter types
are **IP filters** (type `ip`) and **VPC filters** (type `vpce`).

## Jobs to Be Done

- Create an IP filter to restrict ingress to specific IPs or CIDR blocks
- Create a VPC filter (AWS PrivateLink) to restrict traffic to specific VPC endpoint IDs
- List, inspect, update, and delete network security policies
- Look up PrivateLink region metadata (service names, domain names, availability zones)
- Associate or disassociate filters with Serverless projects (delegates to **cloud-manage-project**)
- Audit the current network security posture for an organization

## Prerequisites and permissions

| Item            | Description                                                                                 |
| --------------- | ------------------------------------------------------------------------------------------- |
| **EC_API_KEY**  | Cloud API key (set by **cloud-setup**). Required for all operations.                        |
| **Region**      | Filters are region-scoped. The user must specify the target region when creating filters.   |
| **Project IDs** | Required only when associating filters with projects (handled by **cloud-manage-project**). |

Run `python3 skills/cloud/network-security/scripts/cloud_network_security.py list-filters` to verify that `EC_API_KEY`
is valid before proceeding with any operation.

### Operation-level permissions

The following permissions are required for common network security operations in Elastic Cloud Serverless.

| Operation                        | Required permission                       |
| -------------------------------- | ----------------------------------------- |
| List filters / get metadata      | Any organization member                   |
| Create / update / delete filters | Organization owner (`organization-admin`) |
| Associate filters with projects  | Organization owner or project Admin       |

This skill does not perform a separate role pre-check. Attempt the requested operation and let the API enforce
authorization. If the API returns an authorization error (for example, `403 Forbidden`), stop and ask the user to verify
the provided API key permissions.

### Manual setup fallback (when cloud-setup is unavailable)

If this skill is installed standalone and `cloud-setup` is not available, instruct the user to configure Cloud
environment variables manually before running commands. Never ask the user to paste API keys in chat.

| Variable      | Required | Description                                                                          |
| ------------- | -------- | ------------------------------------------------------------------------------------ |
| `EC_API_KEY`  | Yes      | Elastic Cloud API key (see permissions table above for required roles by operation). |
| `EC_BASE_URL` | No       | Cloud API base URL (default: `https://api.elastic-cloud.com`).                       |

> **Note:** If `EC_API_KEY` is missing, or the user does not have a Cloud API key yet, direct the user to generate one
> at [Elastic Cloud API keys](https://cloud.elastic.co/account/keys), then configure it locally using the steps below.

Preferred method (agent-friendly): create a `.env` file in the project root:

```bash
EC_API_KEY=your-api-key
EC_BASE_URL=https://api.elastic-cloud.com
```

All `cloud/*` scripts auto-load `.env` from the working directory.

Alternative: export directly in the terminal:

```bash
export EC_API_KEY="<your-cloud-api-key>"
export EC_BASE_URL="https://api.elastic-cloud.com"
```

Terminal exports may not be visible to sandboxed agents running in separate shell sessions, so prefer `.env` when using
an agent.

## Decomposing Network Security Requests

When the user describes a network security need in natural language (for example, "restrict my search project to our
office IP"), break the request into discrete tasks before executing.

### Step 1 — Identify the components

| Component       | Question to answer                                                     |
| --------------- | ---------------------------------------------------------------------- |
| **Filter type** | IP filter (public IPs/CIDRs) or VPC filter (AWS PrivateLink endpoint)? |
| **Region**      | Which AWS region are the target projects in?                           |
| **Rules**       | What source IPs, CIDRs, or VPC endpoint IDs should be allowed?         |
| **Scope**       | Apply to all new projects by default, or specific projects only?       |
| **Projects**    | Which existing projects should this filter be associated with?         |

### Step 2 — Check existing state

Before creating a new filter, check what already exists:

```bash
python3 skills/cloud/network-security/scripts/cloud_network_security.py list-filters --region us-east-1
```

**Filter hygiene:** If an existing filter already covers the same source rules **for the same purpose**, reuse it
instead of creating a duplicate. Filters are region-scoped and can be associated with multiple projects, so a single
filter with the right rules serves many projects. Two filters with identical source rules are fine when they serve
different purposes (for example, different teams managing their own policies), but creating a second filter for the same
purpose is unnecessary.

### Step 3 — Create the filter

Run the appropriate command from `skills/cloud/network-security/scripts/cloud_network_security.py`.

### Step 4 — Associate with projects

Filter association is managed using the project PATCH endpoint. Use **cloud-manage-project** to associate or
disassociate filters:

```text
PATCH /api/v1/serverless/projects/{type}/{id}
Body: { "traffic_filters": [{ "id": "filter-id-1" }, { "id": "filter-id-2" }] }
```

When updating associations, provide the **complete list** of filter IDs. Any filter not included in the list is
disassociated from the project.

### Step 5 — Verify

After execution, list filters again or GET the project to confirm the change took effect.

## IP Filters versus VPC Filters

| Aspect            | IP Filter (`ip`)                                   | VPC Filter (`vpce`)                                      |
| ----------------- | -------------------------------------------------- | -------------------------------------------------------- |
| **Purpose**       | Allowlist public IP addresses or CIDR blocks       | Restrict traffic to specific AWS VPC endpoint IDs        |
| **Use case**      | Office IPs, CI/CD runners, partner access          | Private connectivity without public internet exposure    |
| **Source format** | IP address or CIDR (for example, `203.0.113.0/24`) | AWS VPC endpoint ID (for example, `vpce-0abc123def456`)  |
| **Network path**  | Public internet                                    | AWS P