syslog-server/README.md

# syslog-server

![TypeScript](https://img.shields.io/badge/TypeScript-3178C6?logo=typescript&logoColor=white)
![AWS CDK](https://img.shields.io/badge/AWS-CDK-FF9900?logo=amazonaws&logoColor=white)
![CI](https://github.com/Sea-Haven-Industries/syslog-server/actions/workflows/ci.yaml/badge.svg)

CDK stack for the **syslog-server** EC2 collector: receives remote syslog
(UDP/TCP 514) from the office UniFi fleet over its Elastic IP and ships it to
the `unifi-syslog` CloudWatch Logs group via the CloudWatch agent.

Brought under IaC for **INFRA-12** (AWS audit L-6). Previously a console/CLI
instance with no drift detection.

## Architecture

```
office UniFi devices ──syslog/514──▶ EIP 184.72.154.32 ──▶ EC2 (rsyslog)
                                                              │
                                              /var/log/remote/<host>/*.log
                                                              │
                                              CloudWatch agent ──▶ unifi-syslog (90d)
                                                                        │
                                                       Syslog-NoIncomingLogs alarm ──▶ site-alerts
```

| Resource | Value |
|---|---|
| Instance | `syslog-server`, t4g.nano, Amazon Linux 2023 (arm64), 30 GiB encrypted gp3 |
| Subnet | `subnet-0eea820effe1b3ae5` (public, us-east-1a, `vpc-0d3d4b67bd0cf8a68`) |
| Elastic IP | `184.72.154.32` (`eipalloc-006bdefc9802f3285`) — **unmanaged**, re-associated by ID |
| Security group | `syslog-server` — 514 tcp/udp + 22 from office IPs + VPC/VPN CIDRs; 2055/2056 udp reserved (netflow/sflow) |
| IAM role | `syslog-server-role` — `AmazonSSMManagedInstanceCore` + `CloudWatchAgentServerPolicy` |
| Log group | `unifi-syslog` (90-day retention) — created/retained by the CW agent, **not** a CFN resource (holds history; see stack comment) |
| Alarm | `Syslog-NoIncomingLogs` — `IncomingLogEvents` Sum < 1 over 2×1-day, ALARM-only → `site-alerts` |

## CDK app

Infrastructure is a single-stack AWS CDK app written in TypeScript. `cdk.json` is
the app manifest the CDK CLI reads on every command: its `app` entry
(`npx tsx bin/app.ts`) runs the TypeScript entry point directly through `tsx`, so
`synth`/`deploy` need no separate `tsc` compile step. The file also carries the
`watch` globs (for `cdk watch`) and the CDK feature-flag `context`.

| Path | Role |
|---|---|
| `cdk.json` | CDK app manifest — `app` entry command, `watch` globs, feature-flag context |
| `bin/app.ts` | App entry point; instantiates `SyslogServerStack` with explicit `stackName: "syslog-server"` and env pinned to account `328440206208` / `us-east-1` |
| `lib/syslog-server-stack.ts` | The `syslog-server` stack — every resource in the table above (EC2 instance + rsyslog/CloudWatch/NetFlow user-data, security group, IAM role, EIP association, alarms) |
| `cdk.context.json` | Cached provider lookups — the VPC (`vpc-0d3d4b67bd0cf8a68`) and the pinned AL2023 AMI (`cachedInContext`); committed so synth is deterministic |

`aws-cdk-lib` is pinned to an exact version (`2.261.0`). The npm scripts wrap the
CDK CLI — `npm run synth`, `npm run diff`, `npm run deploy` — plus
`npm run build` (`tsc` type-check).

## Documentation

The canonical map of Sea Haven's AWS infrastructure lives in Confluence. This project's `syslog-server` stack is represented there as a Mermaid subgraph.

- **[AWS Architecture Map](https://seahaven.atlassian.net/wiki/spaces/IT/pages/1540098)** (Confluence, IT space, page 1540098)

## Access

SSM Session Manager (no key pair). SSH 22 is open from office/VPC for
break-glass only.

## Deploy

CI/CD via the org reusable workflows (`ci-typescript-cdk.yaml`,
`cd-cdk.yaml`); merges to `main` deploy through the `githubdeploy-syslog-server`
OIDC role. No Docker assets, so a local `cdk deploy` is also safe.

```
npm ci
npm run diff
npm run deploy
```

## Notes

- **EIP is unmanaged.** CloudFormation associates it but never releases it, so
  the public forwarding target survives any instance replacement.
- **AMI is pinned in `cdk.context.json`** (`cachedInContext`). An AL2023 AMI
  change forces instance replacement — refresh deliberately with
  `cdk context --reset <ami key> && cdk synth`.
- To widen device coverage of the forwarded syslog feed, see **INFRA-11**
  (UniFi controller remote-logging config).