Policyseed

policyseed

[npm] [License: Apache-2.0] [MCP Registry]

Free, offline SOC 2 policy generator. policyseed renders 22 governance policy documents from a single YAML intake file, using a small template engine and zero runtime dependencies.

npx policyseed init    # writes intake.yaml: company, cloud, identity provider, MFA, team size...npx policyseed build   # renders the 22 policies into ./policies/

Prefer a browser? The same templates run at policyseed.io/generate: 23 questions, no signup, nothing uploaded.

• Free and Apache-2.0. Use it, fork it, modify it, ship it internally or to customers.
• Deterministic. The same intake.yaml always produces the same Markdown. No randomness.
• No LLM. Templates are plain Markdown with a Mustache-style tag syntax, not model output.
• No signup. No network calls unless you collect evidence. build, check, init, list and mcp make no network calls and run entirely on your machine or CI runner. evidence calls only the cloud CLIs you already use (aws, gcloud, gh), with read-only commands, and only when you run it.

The policies are a starting point that your company reviews and adopts, not a compliance guarantee. See What this is not.

What the output looks like

Every policy names your tools and people from the intake. An excerpt of the Access Control Policy, rendered by npx policyseed build for an example company (AWS, GitHub, Google Workspace, MFA on, 11-50 people):

4.3 Google Workspace is the single source of workforce identity. Business applications are integrated with it for single sign-on and, where supported, automated provisioning and deprovisioning; applications that cannot federate are recorded in the exception register with a compensating review.

4.8 Access to GitHub is granted through organization membership enforced by single sign-on with Google Workspace, repository permissions are assigned by team, and protected branches require a review from someone other than the author before code is merged and deployed by GitHub Actions. Where headcount makes this impractical, the Security Owner documents the compensating review.

All 22 policies share the same nine sections: purpose, scope, roles and responsibilities, numbered policy statements, procedures, exceptions, enforcement, review cadence and revision history. The numbered statements make it easy to point an auditor at the exact sentence behind a control.

Quick start

Requires Node.js 18 or later. No install step — run it with npx:

npx policyseed init# edit intake.yaml with your company's detailsnpx policyseed buildnpx policyseed check

• init writes a commented intake.yaml in the current directory with every field, its allowed values, and sensible defaults. It refuses to overwrite an existing file unless you pass --force.
• build reads intake.yaml, validates it, and writes all 22 policies to ./policies/ as NN-<slug>.md files with a company-titled heading.
• check reads ./policies/ and intake.yaml and exits with status 1 if any policy's last reviewed date is older than its review_cadence allows. This is what the bundled GitHub Action runs on a schedule so an overdue policy shows up as a failing check.
• list prints the 22 bundled templates.
• evidence collects read-only SOC 2 evidence from AWS, Google Cloud and GitHub with the CLIs you already have signed in. See Collecting audit evidence.
• --help and --version do what you'd expect.

If you'd rather install it as a dependency:

npm install --save-dev policyseednpx policyseed init

Template syntax reference

Templates are plain Markdown files with YAML front matter and a small set of tags, implemented in lib/render.js:

Truthiness matches JavaScript, plus empty arrays count as falsy: false, "", 0, NaN, null, undefined and [] are falsy; everything else is truthy.

A block tag that stands alone on its own line (only whitespace before and after it) is removed together with its line, so conditional paragraphs and loops don't leave stray blank lines behind. Three or more consecutive blank lines collapse to two.

The context available to every template is built by toTemplateContext() in lib/context.js from your intake.yaml — company name, cloud providers, identity provider, MFA status, data types handled, and so on, plus derived booleans like has_mdm, has_vendors, scope_availability and small_team (headcount 1-10) that templates branch on.

The 22 policies

Each one has nine standard sections: Purpose, Scope, Roles and Responsibilities, Policy Statements, Procedures, Exceptions, Enforcement, Review Cadence, and Revision History.

Keeping policies current in CI

Use the GitHub Action in a repo that keeps intake.yaml and policies/ under version control:

- uses: actions/checkout@v4- uses: odedmoshe/policyseed@v1  with:    command: check

It fails the check when a policy is overdue for review, so a stale policy shows up as a red X instead of quietly rotting. .github/workflows/policy-review.yml is a complete weekly workflow to copy; inputs and outputs are in docs/github-action.md.

Use it from an AI assistant (MCP)

policyseed mcp starts a Model Context Protocol server, so Claude, Cursor and other MCP clients can list the policies, ask you the intake questions and render any policy in the conversation. Nothing leaves your machine except what you type to the assistant.

claude mcp add policyseed -- npx -y policyseed mcp

Claude Desktop and Cursor configuration, the tool list and an example conversation are in docs/mcp.md.

Agent skill

skills/soc2-policies/ is an agent skill (a SKILL.md plus an interview guide) that tells Claude Code and other skill-aware agents when to use Policyseed and how: interview for the intake, render with the CLI or the MCP tools, then report what to review. To install it for Claude Code, copy the folder into ~/.claude/skills/ (or .claude/skills/ in a project).

Collecting audit evidence

Auditors ask for proof that controls are configured: branch protection, MFA, encryption at rest, logging, who has admin access. policyseed evidence gathers that with the aws, gcloud and gh CLIs you already have installed and signed in, and saves it as dated JSON files plus an index:

npx policyseed evidence --providers aws,gcp,github \  --repo acme/app --org acme --project acme-prod

evidence/2026-10-23/  INDEX.md                                 criterion -> file -> what it shows -> auditor question  CC6.1-aws-iam-account-summary.json  CC6.1-aws-iam-credential-report.json  CC8.1-github-branch-protection.json  ...

How it behaves:

• Read-only. Every command is a Describe, Get or List call (gh api GET requests, no request fields). The one exception in name only is aws iam generate-credential-report, which asks IAM to build the credential report; IAM classifies it as a Read action and it changes no settings. --dry-run prints the exact commands without running anything; --list prints the collectors.
• No shell. Each command runs with Node's execFile and a fixed argument array. --repo, --org, --project, bucket names and trail ARNs are passed as separate arguments, never interpolated into a shell string. Pagers and interactive prompts are turned off.
• Each file wraps the CLI's JSON output with the command that produced it, the time, the CLI version and the exit code. Files are named <criterion>-<collector-id>.json after the collector's first SOC 2 criterion; INDEX.md lists every criterion a file supports.
• Redaction. Before anything is written or printed, values under secret-looking keys (SessionToken, SecretAccessKey, password, token, ...) are replaced, and so are strings that look like credentials: GitHub tokens, AWS access key IDs and session tokens, Google API keys and OAuth tokens, JWTs, PEM private keys and key=value secrets. Secrets are never requested in the first place. Account IDs are kept, because auditors usually need them; pass --redact-account-ids to truncate 12-digit IDs to their last four digits.
• Failures don't stop the run. A missing CLI, missing credentials or a permission error is written to INDEX.md as not collected: <reason> and the run moves on. The exit code is 1 only if nothing at all was collected.
• Re-runs. A run replaces the files its providers wrote earlier the same day and rewrites INDEX.md. Other days' folders, other providers' files and any files you add yourself (such as screenshots) are left alone.
• Scope. Regional AWS checks (EBS default encryption, RDS, CloudTrail) use the CLI's configured region (AWS_REGION or the profile's region). GitHub checks cover one repository and one organization; Google Cloud checks cover one project (--project, or the gcloud default). S3 per-bucket checks stop after --max-buckets buckets (default 50). On Windows, gcloud is a .cmd script that Node can't start without a shell, so the Google Cloud collectors report it as not collected there.

What it collects

All aws commands add --output json and all gcloud commands add --format=json.

Permissions it needs

Give the identity you run it with read access only.

AWS. This policy covers every AWS collector and nothing else:

{  "Version": "2012-10-17",  "Statement": [    {      "Sid": "PolicyseedEvidenceReadOnly",      "Effect": "Allow",      "Action": [        "iam:GetAccountSummary",        "iam:GenerateCredentialReport",        "iam:GetCredentialReport",        "iam:GetAccountPasswordPolicy",        "cloudtrail:DescribeTrails",        "cloudtrail:GetTrailStatus",        "ec2:GetEbsEncryptionByDefault",        "s3:ListAllMyBuckets",        "s3:GetEncryptionConfiguration",        "s3:GetBucketPublicAccessBlock",        "rds:DescribeDBInstances"      ],      "Resource": "*"    }  ]}

Google Cloud. roles/viewer on the project covers the project collectors, and roles/resourcemanager.organizationViewer on the organization covers organizations list. For narrower access, grant roles/iam.securityReviewer (IAM policy), roles/logging.viewer (sinks), roles/cloudsql.viewer (SQL instances) and roles/compute.viewer (disks) on the project.

GitHub. gh uses whatever it is signed in with (gh auth login, or GH_TOKEN). Repository admin read access is needed for classic branch protection, the security_and_analysis block and the Dependabot alerts setting; the ruleset rules need only read access. For the organization, GitHub returns two_factor_requirement_enabled only to organization owners, and lists private members only to members. A fine-grained token with repository Administration: read and Metadata: read and organization Members: read covers the rest. A collector the token can't read is recorded as not collected, never as a pass.

To run the GitHub collectors on a schedule and keep the results as a workflow artifact, see docs/evidence.md.

What it does not do

It saves configuration as it is on the day you run it. It doesn't judge whether that configuration meets your policies, it doesn't cover every control an auditor will test, and it doesn't replace the auditor's own testing: they will choose their own samples, may ask you to re-run commands while they watch, and will test whether the controls operated over the whole audit period.

Relationship to the hosted generator and Audit Kit

This package is the same rendering engine that powers the hosted generator at policyseed.io, packaged for people who'd rather run it locally, script it into CI, or read exactly how it works; the hosted site also offers a paid Audit Kit that uses Claude to tailor the Policy Statements and Procedures sections to your specific stack and adds export formats — this CLI does not include that tailoring step.

What this is not

These are governance document templates, not legal advice, and not a compliance guarantee. A SOC 2 report is an independent CPA firm's opinion, and it depends on whether you actually operate the controls these policies describe — access reviews happening on schedule, incidents actually being logged and triaged, backups actually being tested — not just on having the documents. Have a qualified person (counsel, an auditor, or an experienced compliance practitioner) review the output before you rely on it externally.

Contributing

Issues and pull requests are welcome at github.com/odedmoshe/policyseed. If you're proposing a change to a policy's wording, prefer editing the template's prose directly and running the test suite (node --test test/) so the renderer parity and CLI smoke tests still pass. If you're adding a new intake field, update lib/context.js (DEFAULT_INTAKE, toTemplateContext, validateIntake) together, since the three are meant to stay in lockstep.

License

Apache License 2.0 — see LICENSE. Copyright the policyseed contributors.