# Secure Coding Standards

**Document Version**: 1.0  
**Last Updated**: 2025-10-03  
**Owners**: Platform Security Guild

This standard defines the static and dynamic analysis requirements for every
code change merged into the Lilith monorepo. All engineers must follow the
practices below and ensure the automated checks run before raising a pull
request.

## Principles

1. **Shift-left security** – security defects are addressed during development
   via automated linting, type safety, and code reviews.
2. **Single source of truth** – the commands and tooling listed here are
   codified in `package.json` scripts and enforced by Playwright compliance
   tests.
3. **Zero tolerated bypasses** – disabling or weakening security checks is
   prohibited; instead, fix the underlying issue or work with the Security Guild
   on approved exceptions.

## SAST (Static Application Security Testing)

Purpose: detect insecure coding patterns, dependency misuse, and violations of
the Lilith secure coding guidelines before runtime.

- Run `npm run security:sast` prior to every commit.
- The command executes `eslint` with the TypeScript ruleset and a full
  type-check via `tsc --noEmit`.
- Failing lint or type errors must be resolved; do **not** use
  `// eslint-disable` without an approved ADR.
- Reports are captured during CI in `artifacts/security/sast/` for traceability.

## DAST (Dynamic Application Security Testing)

Purpose: validate runtime behaviour, configuration, and documentation alignment
for the security surface.

- Run `npm run security:dast` after SAST passes.
- The command executes the security Playwright compliance suite
  (`tests/security.threat-model.spec.ts`,
  `tests/security.audit-logging.spec.ts`,
  `tests/security.secure-coding.spec.ts`), validating policy documentation and
  runtime contracts.
- Extend this suite whenever new services or policies are introduced (example
  patterns live in `tests/security.audit-logging.spec.ts`).

## Dependency Scanning

Purpose: flag vulnerable transitive and direct dependencies and enforce timely
remediation.

- Run `npm run security:scan` at least once per workday and before merging.
- The script executes `npm audit --audit-level=high`, failing on known
  high/critical advisories.
- Security Guild reviews the audit report weekly and tracks remediation SLAs in
  the dependency risk board.

## Developer Workflow Checklist

| Step | Command                 | Outcome                                                                |
| ---- | ----------------------- | ---------------------------------------------------------------------- |
| 1    | `npm run security:sast` | Type-safe linting (ESLint) + compiler analysis                         |
| 2    | `npm run security:dast` | Security Playwright suite exercising documentation & runtime contracts |
| 3    | `npm run security:scan` | Dependency advisory scan with high/critical fail gate                  |

## Tooling Integration

- Pre-commit hooks execute `npm run security:sast` on staged files (see
  `.husky/pre-commit`).
- CI pipelines run all three commands on every branch and publish results in the
  Security Dashboard.
- Playwright compliance tests ensure this document stays aligned with the
  configured scripts.

## Exceptions & Governance

- Temporary exceptions require approval from the Platform Security Guild and
  must be documented in `docs/adr/`.
- Exceptions expire after 14 days unless renewed with evidence of mitigation
  work.
- The Security Guild audits adherence each quarter and updates this policy as
  tooling evolves.
