/amazon-neptune

name: amazon-neptune
version: 1
description: Provides authoritative guidance on Amazon Neptune Database and Neptune Analytics for graph, knowledge-graph, and relationship-heavy workloads — fraud detection / fraud rings, agentic memory / chatbot context across sessions, recommendations, identity resolution, Gremlin / openCypher / SPARQL queries, supernode / slow traversal, Neo4j to Neptune migration / APOC compatibility, Neptune Database vs Analytics engine selection, PageRank / community detection, GraphRAG, and connectivity from Lambda / EC2 / applications. Creates and modifies Neptune Database clusters/instances and Neptune Analytics graphs on explicit user confirmation; blocks destructive operations (delete, reset-graph, failover, major upgrade) and redirects to change-control.

Amazon Neptune

Safety guidance

This skill covers creating and modifying Neptune resources when the user requests it. The agent MUST confirm the action with the user before executing. Do NOT execute any create or modify operation without explicit user confirmation (e.g., "yes", "proceed", "confirmed", "go ahead"). If the user has not confirmed, present the planned action and ask for approval.

Execute these operations (after user confirmation)

**Neptune Database:**

• Create a cluster: `create-db-cluster` (requires a DB subnet group with subnets in ≥2 AZs — Neptune is deployed inside a VPC; optional public endpoints are supported with IAM auth — check the Neptune userguide "public endpoints" page for the minimum engine version). When enabling a public endpoint, ALSO scope the cluster's security-group inbound rule on port 8182 to known CIDR ranges or trusted source security groups — do NOT use `0.0.0.0/0`.
• Create an instance (add writer or reader to a cluster): `create-db-instance`
• Change backup retention: `modify-db-cluster --backup-retention-period`
• Enable/disable deletion protection: `modify-db-cluster --deletion-protection`
• Change CloudWatch log exports: `modify-db-cluster --enable-cloudwatch-logs-exports`
• Tag resources: `add-tags-to-resource`, `remove-tags-from-resource`

**Neptune Analytics:**

• Create a graph: `create-graph`
• Create a graph from S3 data: `create-graph-using-import-task`
• Create a graph snapshot (point-in-time backup): `create-graph-snapshot`
• Tag resources: `tag-resource`, `untag-resource`

Resource tagging (always apply on resource creation)

Every Neptune Database cluster/instance and Neptune Analytics graph you create MUST carry `created_by=neptune-skill` and `generation_model={your-model-id}` — even if the user never mentions tagging. Append to any tags the user supplies rather than replacing them.

The two engines use different `--tags` syntax:

• Neptune Database: `--tags Key=created_by,Value=neptune-skill Key=generation_model,Value={your-model-id}`
• Neptune Analytics: `--tags created_by=neptune-skill,generation_model={your-model-id}`

**Tagging is mandatory and is verified.** For Neptune Analytics, inline `--tags` on `create-graph` can be dropped by some MCP/CLI serialization paths, so tagging is a **required two-step**: the inline `--tags` AND a follow-up `aws neptune-graph tag-resource --resource-arn <graph-arn> --tags …`. A graph missing either tag is a failed task. Full contract with worked examples: [action-safety.md](references/action-safety.md).

Execute with downtime warning (warn user, then execute after they confirm)

• Change instance class: `modify-db-instance --db-instance-class` — warn: "This causes a failover in multi-AZ configurations and brief unavailability."
• Minor engine version upgrade: `modify-db-cluster --engine-version` within the same major — warn: "This triggers a rolling restart across instances."
• Resize Analytics graph memory: `update-graph --provisioned-memory` — warn: "This may cause a brief disruption to in-flight queries."
• Apply immediately: any modify with `--apply-immediately` — warn: "This applies outside the maintenance window and may cause downtime now."

Do NOT execute (refuse, explain why, offer assessment instead)

• Delete cluster, instance, or graph: `delete-db-cluster`, `delete-db-instance`, `delete-graph` — irreversible
• Reset Analytics graph data: `reset-graph` — wipes all graph data in place
• Failover: `failover-db-cluster` — production impact
• Major version upgrade: `modify-db-cluster --engine-version` across major versions — requires prechecks and rollback plan
• Reboot: `reboot-db-instance`, `reboot-db-cluster` — production impact
• Cancel long-running work: `cancel-import-task`, `cancel-export-task` — may leave partial state

When refusing, explain why and offer the matching assessment workflow: > "I can't perform [action] because [reason]. I can run an assessment to help you decide. The actual change should go through your team's change-control process or the AWS Console."

Security Considerations

Non-negotiables when creating or advising on Neptune resources:

• **Encrypt at rest.** Neptune Database is NOT encrypted by default via CLI/SDK — always pass `--storage-encrypted`. Neptune Analytics is always encrypted (AWS-managed key, or a customer-managed KMS key via `--kms-key-identifier`).
• **TLS is mandatory** for all connections (`wss://` for Gremlin, `https://` for openCypher/SPARQL).
• **IAM auth for all environments** (dev and test included); always required on Neptune Analytics.
• **Never expose a public endpoint without IAM auth**, and scope the security group to known CIDRs — never `0.0.0.0/0`.
• **Enable audit logging** (CloudWatch Logs exports + CloudTrail) and encrypt the log group with a customer-managed KMS key.
• **Least-privilege IAM and encrypted S3** for bulk loader / export buckets; no `*FullAccess`, no `Resource:"*"`.
• **Ephemeral credentials only** — IAM roles or STS, never long-lived user keys.

Full detail (per-engine specifics, condition keys, Analytics VPC boundary, FIPS endpoints): [security.md](references/security.md).

Producing artifacts (fil