Customization

speckit-security is designed to be vendor-agnostic. You can adapt it to your team's conventions, tools, and policies without forking the repo. This page walks through every supported customization point in v0.3.1.

1. Configuration file

The primary customization surface is per-project:

.specify/extensions/tekimax-security/tekimax-security-config.yml

Copy the template after installing the extension:

cp .specify/extensions/tekimax-security/config/tekimax-security-config.template.yml \
   .specify/extensions/tekimax-security/tekimax-security-config.yml

Enforcement mode

enforcement: warn        # warn = hooks advise but never block
                         # strict = hooks block on any gate failure

Stack declarations

These are purely informational today: the scripts don't read them. They document what your team uses so threat models, templates, and spec authors can reference the right tools. Treat them as metadata for humans and AI agents reading the config, not as enforcement knobs.

stack:
  ai_gateway: <your-ai-gateway>
  guardrails: <your-guardrail-provider>
  pii_encryption: field-level-encryption
  rbac: <your-rbac-provider>
  runtime: <your-runtime>
  schema: zod
  storage: <your-storage>

Required spec sections (planned)

The intended config declares which sections a feature spec must contain:

required_sections:
  - "Data Contract"
  - "AI Integration"
  - "Security"
  - "Verification"

⏳ Not yet read by the scripts. Today gate-check.sh hardcodes the section names it looks for (## Data Contract / ## 2. Data Contract, ## Security / Threat Model / ## Security). To add a new required section today, edit the check_section calls in gate-check.sh directly, or fork the repo. Config-driven read-back is planned for a later release.

2. Environment variables

The bash scripts read these environment variables:

3. Template overrides

speckit-security ships seven reference templates under templates/. You can override any of them without touching the extension by using Spec Kit's standard template resolution stack:

1. Project-local overrides, .specify/templates/overrides/
2. Installed template packs, .specify/templates/packs/<pack-id>/
3. Extension-provided templates, .specify/extensions/tekimax-security/templates/
4. Core templates

To override the STRIDE threat model template:

mkdir -p .specify/templates/overrides
cp .specify/extensions/tekimax-security/templates/threat-model-stride.md \
   .specify/templates/overrides/threat-model-stride.md
# edit the copy to match your conventions

The AI agent will pick up your version on the next /speckit.tekimax-security.threat-model run.

4. Allowlisting direct SDK imports

The post-implementation audit flags direct model SDK imports outside your AI gateway layer. By default any file whose path contains src/ai/gateway is allowed. You can extend that list via config:

audit:
  allowlist:
    stack_direct_sdk:
      - "src/platform/ai-proxy"
      - "packages/gateway"

Entries are substring matches against the file path, so src/platform/ai-proxy matches both src/platform/ai-proxy.ts and src/platform/ai-proxy-test.ts. The built-in src/ai/gateway entry stays active — user entries extend, they don't replace.

The allowlist is also honored by Gate F's inline-prompt check: files under an allowlisted path can reference inline system prompts legitimately (because they're part of the gateway), so they won't trip Gate F.

5. Adjusting secret and inline-prompt patterns

Both gate-check.sh and audit.sh ship a built-in set of secret and inline-prompt patterns that cover the most common AWS, GCP, GitHub, Slack, and Stripe tokens, PEM private keys, and assistant system-prompt markers. Add your own extensions in config:

audit:
  inline_prompt_patterns:
    - "// PROMPT-START"           # internal marker your team uses
    - "ASSISTANT_PROMPT_V[0-9]"

  secret_patterns:
    - "ACME_PROD_[0-9a-z]{24}"     # company-internal token prefix
    - "INTERNAL_BEARER_"

User entries are additive: they extend the built-in alternation rather than replacing it, so you keep full default coverage plus your custom rules. Patterns are ERE (extended regex), same as grep -E.

audit.file_scope is not yet honored; the scripts still use a fixed set of grep --include flags (*.ts, *.tsx, *.js, *.jsx, *.py, and *.env* for the audit secret scan). File scope customization is tracked as a follow-up.

6. Red team runner configuration

red_team:
  staging_url: "${SPECKIT_TEKIMAX_SECURITY_STAGING_URL}"
  max_rps: 10
  never_run_against:
    - "prod"
    - "production"

What the script honors:

• ✅ red_team.staging_url, read from config. The env var SPECKIT_TEKIMAX_SECURITY_STAGING_URL takes precedence if both are set.
• ✅ red_team.max_rps, read from config (new in v0.2.5). The env var SPECKIT_TEKIMAX_SECURITY_MAX_RPS takes precedence. Default is 10 if neither is set.
• 🛈 red_team.never_run_against, not read from config on purpose. The script enforces a hardcoded regex refusal on (^|[^a-z])prod([^a-z]|$) and production as a defense-in-depth measure — making this user-overridable would let a misconfigured project accidentally fire scenarios at prod.

7. Enabling / disabling hooks

Disable one hook by making it interactive

Edit .specify/extensions/tekimax-security/extension.yml and change optional: false to optional: true for the hook you want to suppress:

hooks:
  before_implement:
    command: "speckit.tekimax-security.gate-check"
    optional: true   # was false, now prompts instead of auto-running

This edits the installed copy in .specify/, not the upstream repo. Reinstalling the extension resets the change.

Disable the entire extension temporarily

specify extension disable tekimax-security
# ... work without gates ...
specify extension enable tekimax-security

Remove the extension entirely

specify extension remove tekimax-security

8. Fork or write a sibling extension

If configuration isn't enough:

• Fork: gh repo fork TEKIMAX/speckit-security --clone and modify. Please also open an issue upstream so broadly useful changes can be merged back.
• Sibling extension: write your own Spec Kit extension that coexists with speckit-security. See the Spec Kit Extension Development Guide.