Nextellar takes security seriously. This document defines our dependency vulnerability management policy, severity gates, and remediation procedures.

We follow npm audit severity classifications:

Automated checks run on:

• Every push to main and develop branches
• Every pull request modifying package.json
• Daily scheduled audits (2 AM UTC)
• Manual workflow dispatch

CI/CD Build Status:

• ✅ PASS - 0 critical, 0 high vulnerabilities
• ⚠️ WARN - Moderate vulnerabilities detected (allowed to merge, must remediate within 30 days)
• ❌ FAIL - Any critical or high severity vulnerabilities (blocks merge)

Rule Details:

if (critical > 0 || high > 0) {
  FAIL_BUILD = true
  block_merge = true
  create_security_issue = true
  notify_team = true
}

if (moderate > 0 && critical === 0 && high === 0) {
  WARN_BUILD = true
  allow_merge = true
  create_issue = true
  set_due_date = today + 30 days
}

if (low > 0 && critical === 0 && high === 0 && moderate === 0) {
  PASS_BUILD = true
  log_for_tracking = true
}

All vulnerability audits are:

1. Reported to GitHub Security Tab - SARIF format for native integration
2. Commented on PRs - Summary table with vulnerability counts
3. Tracked in Issues - For moderate/high severity findings
4. Logged in CI Artifacts - Full audit JSON reports retained 30 days

1. Immediate Action (< 24 hours)

   • Assess impact on the project
   • Check for available patches
   • Create security issue with security label

2. Fix Priority

   • Update vulnerable package to latest patch
   • If no patch available, evaluate alternatives
   • If no alternative, isolate vulnerable dependency

3. Verification

   • Run full test suite
   • Re-run audit to confirm fix
   • Deploy immediately after verification

4. Communication

   • Document in security issue
   • Link to pull request
   • Post-mortem analysis for patterns

1. Assessment (within 3 days)

   • Evaluate if vulnerability is exploitable in our context
   • Review patch availability and changelog
   • Estimate update effort

2. Remediation (within 30 days)

   • Create issue with due date (current + 30 days)
   • Plan update in next sprint
   • Prioritize if affecting production

3. Tracking

   • Link to milestone
   • Assign to team member
   • Track in security dashboard

1. Tracking (periodic review)
   • Monitor in audit reports
   • Include in quarterly reviews
   • Update when major version bumps

Enabled for:

• Security updates (automatic PR creation + merge)
• Minor version updates (PR only, manual merge)
• Patch version updates (PR only, manual merge)

Configuration:

version: 2
updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "weekly"
      day: "monday"
      time: "03:00"
    open-pull-requests-limit: 10
    pull-request-branch-name:
      separator: "/"
    reviewers:
      - "security-team"
    allow:
      - dependency-type: "direct"
      - dependency-type: "indirect"
    ignore:
      # Add packages to ignore long-term broken releases, etc.

1. Review - Check changelog for breaking changes
2. Test - Run full test suite locally
3. Verify - Re-audit after update
4. Commit - Clear commit message with reason
5. Deploy - Follow release process

Certain vulnerabilities may be excluded from the policy due to:

• False positives - Vulnerability doesn't apply to our usage
• Transitive only - Affects deep dependency not directly used
• Intentional risk - Documented exception with justification
• EOL software - Acknowledged debt item in backlog

Exclusion process:

1. Document in .npmrc or audit comments
2. Create GitHub issue with label vulnerability-exception
3. Include detailed justification
4. Set review date (quarterly minimum)

Example .npmrc:

# Security: exclude false positives and known issues
audit-level=moderate
fund=false
legacy-peer-deps=false

Approved Licenses:

• Apache-2.0, Apache-2.0+
• MIT, MIT+
• ISC, BSD, BSD-2-Clause, BSD-3-Clause, 0BSD
• MPL-2.0
• LGPL-2.1, LGPL-3.0
• Unlicense

Restricted Licenses:

• GPL (requires review - may require COPYING file)
• AGPL (generally not permitted without explicit approval)
• SSPL (commercial license - requires assessment)

Process for restricted licenses:

1. Create issue with license-review label
2. Document business justification
3. Obtain approval from legal/security team
4. Document exception in project

Vulnerabilities are detected via:

1. GitHub Dependabot - Native GitHub detection
2. npm audit - Local and CI scanning
3. CodeQL Analysis - Code-level security issues
4. Security reports - Manual reports from community

Upon detection:

1. Assess actual impact vs. theoretical risk
2. Determine if it affects production systems
3. Check if already patched
4. Estimate effort to fix

• Internal - Slack notification to #security
• Public - GitHub security advisory (if applicable)
• Users - Security bulletin (for production incidents)

Beyond dependency management:

1. Code Review - All PRs require review
2. Testing - Full test coverage maintained
3. SAST - Static analysis via CodeQL
4. Secrets - Never commit credentials (git-secrets enabled)
5. Validation - Input validation on all entry points
6. Dependencies - Minimize external dependencies
7. Pinning - Use exact versions for production

• Total vulnerabilities by severity
• Time-to-remediation by severity
• Mean audit time
• False positive rate
• Vulnerability density (vuln/1000 LOC)

• Daily - Automated CI reports
• Weekly - Summary to team
• Monthly - Metrics dashboard review
• Quarterly - Full security audit + exceptions review

GitHub Security tab: Settings > Security > Dependabot for:

• Dependency alerts
• Code scanning alerts
• Security advisories

If you discover a security vulnerability:

1. Do not open a public GitHub issue

2. Do email security@nextellar.dev with:

   • Description of vulnerability
   • Steps to reproduce
   • Potential impact
   • Your contact information

3. We will:

   • Acknowledge receipt within 24 hours
   • Provide updates every 7 days
   • Credit you in security advisory (optional)
   • Work toward public disclosure timeline

• npm audit - Built-in Node.js dependency auditing
• GitHub Dependabot - Automated dependency updates
• CodeQL - Static analysis and code scanning
• Dependency Review - GitHub Actions for license/vulnerability review

Install locally:

# npm audit (built-in)
npm audit

# npm audit fix
npm audit fix

# Specific auditing
npm audit --audit-level=moderate
npm audit --json > audit-report.json

Added to package.json:

{
  "scripts": {
    "audit": "npm audit --audit-level=moderate",
    "audit:fix": "npm audit fix",
    "audit:strict": "npm audit --audit-level=low"
  }
}

In addition to dependency vulnerabilities, CI scans every push to main and every pull request for accidentally committed secrets (API keys, private keys, access tokens, etc.) using TruffleHog.

Workflow: .github/workflows/secret-scanning.yml

How it works:

• On a pull request, only the commits introduced by that PR are scanned (base = the PR's base commit, head = the PR's head commit) — pre-existing history is not re-flagged on every run.
• On a direct push to main, the pushed commit range is scanned.
• --only-verified restricts findings to secrets TruffleHog has actively verified against the issuing service (e.g. confirmed a live AWS key actually authenticates), which keeps the check low-noise — it will not fail the build on a string that merely looks like a key.
• --fail causes the job (and therefore the check) to fail if any verified secret is found, blocking the PR from being merged until it's addressed.

If the check fails:

1. Read the job log for the flagged file, line, and detector type.
2. Rotate the credential immediately at the issuing service — assume it is compromised the moment it was pushed, even if you plan to remove it from history.
3. Remove the secret from the current commit (amend or a new commit) and, if it was pushed to a shared branch, treat the exposure as already public: rotating the credential is the actual fix, not just deleting the line.
4. Add the credential to .env / your secret manager instead, and confirm .env* is covered by .gitignore.

Local prevention: the pre-commit hook (see CONTRIBUTING.md) does not run a secret scan — it only lints and formats staged files. Avoid staging real credentials at all; use .env.local (already gitignored) for anything sensitive during local development.

• npm audit documentation
• GitHub Dependabot
• OWASP Dependency-Check
• CWE Top 25
• NPM Security Best Practices

• Established severity gates
• Defined remediation timelines
• Enabled automated auditing
• Created incident response procedures

Contact: security@nextellar.dev or open a discussion in GitHub.

Last Updated: 2026-08-24
Next Review: 2026-11-24
Status: ✅ Active