Skip to content

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

DenDenMushi Nest Backend

NestJS APIs for change requests, inventory, access policy, memberships, and Cognito user administration.

This backend owns authenticated web application data APIs, STS inventory/change-request lookups, Cognito administration, readiness, and CloudWatch monitoring views. It does not proxy terminal streams or issue session tokens.

All application APIs use the /ddm prefix. Kubernetes probes are intentionally outside that prefix:

GET /healthz
GET /readyz

Business endpoints require x-api-version: 1. GET /healthz, GET /readyz, GET /openapi.yaml, /, /ddm/auth/login, /ddm/auth/logout, and /ddm/monitoring/alerts/webhook are exempt so probes, browser redirects, and SNS delivery do not need custom headers. Successful probe request logs are suppressed; failed probe responses still emit request logs.

/healthz only reports that the process is running. /readyz executes SELECT 1 and returns 503 while PostgreSQL is unavailable.

Authentication

AUTH_MODE=dev enables the local JWT login flow for development.

Production requires AUTH_MODE=alb. The backend verifies both AWS ALB authentication headers:

  • x-amzn-oidc-data: signature, expiry, signer ALB ARN, issuer, and client ID.
  • x-amzn-oidc-accesstoken: signature, expiry, issuer, client ID, and token use.

The verified sub values must match. Cognito groups are taken from the access token and mapped to application roles. Requester, approver, and audit actor fields are always derived from this authenticated identity.

GET /ddm/auth/login
GET /ddm/auth/logout

Login is an ALB authentication entry point. Logout expires the ALB session cookie and all four possible cookie shards, disables caching of the response, and redirects through the Cognito logout endpoint. APP_LOGOUT_URI must point to an unauthenticated landing page that is registered as an allowed Cognito sign-out URL.

All responses disable caching and include MIME-sniffing, framing, and referrer protections. The Express X-Powered-By banner is disabled. Production uses same-origin browser APIs and leaves CORS disabled. Local development may set CORS_ENABLED=true and a comma-separated CORS_ORIGINS list of exact http:// or https:// origins. Wildcards and credentialed cross-origin requests are intentionally unsupported.

Development

npm ci
npm run start:dev
npm test -- --runInBand
npm run build

Use .env.example as the configuration reference. Local development may use the individual DB_* settings. Production must use DATABASE_URL and set DB_SSL=true; application startup and migrations reject production configuration that does not enable database TLS.

Dependency security

npm run audit:prod checks production dependencies against the reviewed audit policy and retains the native findings in npm-audit.json. npm run test:audit-policy verifies enforcement, including the expiry of reviewed exceptions. High and critical findings fail CI.

Database Migrations

Sequelize model synchronization is disabled. Apply versioned migrations before rolling out a new backend image:

npm run migrate

premigrate runs npm run build automatically so compiled migration files exist.

Versioned migrations create all domain tables. The initial migration seeds the six default access policies and creates alert event history tables. Apply migrations before starting the app in any shared or production environment.

Container

The Docker image uses Node.js 22, compiles the application and migrations in a builder stage, installs production dependencies only, and runs as a non-root user on port 3000.

The container entrypoint runs database migrations before starting the API. Set SKIP_MIGRATIONS=true to bypass migration on startup when a separate migration job already ran.

STS inventory integration

Terminal session control is handled by Proxy Control Plane and Session Manager, not by this backend. The Angular client calls the public /sessions gateway routes directly after ALB authentication.

The backend also exposes the STS server-inventory contract:

GET /servers/{hostId}
GET /sts/change-requests/{crId}

STS should configure SERVER_INVENTORY_URL=http://nest-backend:3000. The endpoint resolves {hostId} by VM UUID or hostname, returns address data from virtual_machines, and enriches SSH-only metadata from SERVER_INVENTORY_STATIC_JSON or the SERVER_INVENTORY_DEFAULT_* env vars. STS should configure CHANGE_REQUEST_URL=http://nest-backend:3000/sts.

The trusted response includes crId, status, resolved gateway hostIds, implementationStartAt, implementationEndAt, and allowedRoles. Dates are serialized as UTC ISO 8601 strings. These values come from the stored CR; no browser-provided authorization metadata is substituted. An empty VM scope returns hostIds: [], which STS denies. STS requires an explicit role match for ordinary actors; Admin bypasses role matching only. Access-tab visibility is not authorization: STS independently checks approval, window, groups, and scope.

The wire contract is tested in src/change-request/sts-change-request.controller.spec.ts and consumed by the Proxy Control Plane cross-repository integration test.

Session audit facade

Managers, auditors, security analysts, and admins can read retained SSH command/output audit through:

GET /ddm/session-audit/sessions
GET /ddm/session-audit/records
GET /ddm/session-audit/sessions/{sessionId}/records
GET /ddm/audit/events

The backend is only an authenticated facade. It does not proxy terminal traffic, capture command output, store audit bodies, or persist lifecycle events in the webapp database. Configure it with:

SESSION_AUDIT_URL=http://audit-service:8085

GET /ddm/audit/events forwards metadata timeline filters to Audit Service GET /events, including eventType, source, userId, sessionId, hostId, crId, incidentId, runId, from, to, limit, and cursor. The response contains sanitized metadata only.

The session-audit.view permission is granted to Manager, Auditor, SecurityAnalyst, and Admin by default.

CloudWatch monitoring

The monitoring API reads CloudWatch metrics, alarms, and log groups using the nest-backend pod IAM role (IRSA). Set these env vars on the deployment:

CLOUDWATCH_REGION=ap-southeast-1
CLOUDWATCH_LOG_GROUP=/aws/containerinsights/dendenmushi-cluster-dev/application
CLOUDWATCH_SESSION_LOG_GROUP=/aws/containerinsights/dendenmushi-cluster-dev/application
CLOUDWATCH_NAMESPACE=DenDenMushi

Attach a read-only policy to the nest-backend role (for example dendenmushi-nest-backend-dev):

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "CloudWatchReadMetricsAndAlarms",
      "Effect": "Allow",
      "Action": [
        "cloudwatch:DescribeAlarms",
        "cloudwatch:GetMetricStatistics",
        "cloudwatch:ListMetrics"
      ],
      "Resource": "*"
    },
    {
      "Sid": "CloudWatchLogsRead",
      "Effect": "Allow",
      "Action": [
        "logs:FilterLogEvents",
        "logs:DescribeLogGroups",
        "logs:DescribeLogStreams"
      ],
      "Resource": [
        "arn:aws:logs:ap-southeast-1:891377133321:log-group:/aws/containerinsights/dendenmushi-cluster-dev/application",
        "arn:aws:logs:ap-southeast-1:891377133321:log-group:/aws/containerinsights/dendenmushi-cluster-dev/application:*"
      ]
    }
  ]
}

Adjust the account ID, region, and log group ARNs to match your cluster. Without these permissions the monitoring page loads but metrics/logs/alarms stay empty and the API reports awsAuthorized: false.

Optional Redis monitoring cache

Successful CloudWatch alarm and metric queries can be cached in Redis to reduce repeated AWS API calls. The cache is disabled by default and is never used for authentication, authorization, logs, alert records, session state, audit data, or terminal traffic.

REDIS_CACHE_ENABLED=false
REDIS_URL=redis://localhost:6379
MONITORING_CACHE_TTL_SECONDS=60

When enabled, REDIS_URL is required and the TTL must be a positive integer number of seconds. Redis connects asynchronously and is not part of readiness. Cache connection, read, or write failures fall back to CloudWatch, and unsuccessful CloudWatch responses are not cached. Values larger than 256 KiB are also skipped.

For a local container demo, start the optional Compose profile:

REDIS_CACHE_ENABLED=true docker compose --profile cache up --build

GET /ddm/monitoring/status reports the cache provider, enabled state, availability, and TTL. The Kubernetes development environment enables this cache against its internal, non-persistent Redis service:

REDIS_CACHE_ENABLED=true
REDIS_URL=redis://redis.dendenmushi-webapp.svc.cluster.local:6379
MONITORING_CACHE_TTL_SECONDS=60

That Redis pod is a disposable optimization. NetworkPolicy restricts access to Nest Backend, and a restart, suspension, or reschedule may discard all cached values without affecting durable application state.

API contract and CI

OpenAPI contract, served byte-for-byte at GET /openapi.yaml. CI validates it with openapi-spec-validator==0.9.0; handler tests check success, error and API-version responses. Update the specification alongside handler changes.

After successful main CI, the Image workflow builds the tested source SHA and opens a Kubernetes promotion PR with its immutable image digest. Argo CD deploys after that PR is merged; the commit tag provides source traceability.

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages