We actively support the following versions of Semantica with security updates:

We take security vulnerabilities seriously. If you discover a security vulnerability, please follow these steps:

Security vulnerabilities should be reported privately to prevent potential exploitation.

Create a GitHub Security Advisory or contact us via the security email listed in SUPPORT.md.

Include the following information:

• Type of vulnerability (e.g., XSS, SQL injection, authentication bypass)
• Affected component (module, function, or file)
• Steps to reproduce (detailed description or proof-of-concept code)
• Potential impact (what could an attacker do?)
• Suggested fix (if you have one)
• Your contact information (for follow-up questions)

• Initial Response: Within 24 hours for critical issues; within 48 hours for non-critical issues
• Status Update: Within 7 days
• Resolution: Depends on severity and complexity

• We will acknowledge receipt of your report within 48 hours
• We will provide regular updates on the status of the vulnerability
• Once fixed, we will credit you (if desired) in the security advisory
• We will coordinate public disclosure with you

1. Assessment: We assess the severity using CVSS scoring
2. Fix Development: We develop and test a fix
3. Release: We release a security update
4. Advisory: We publish a security advisory on GitHub
5. Communication: We notify users through appropriate channels

• Remote code execution
• Authentication bypass
• Data breach or exposure
• Response Time: Immediate (within 24 hours)

• Privilege escalation
• Significant data leakage
• Denial of service
• Response Time: Within 7 days

• Information disclosure
• Cross-site scripting (XSS)
• CSRF vulnerabilities
• Response Time: Within 30 days

• Minor information leakage
• Best practice violations
• Response Time: Next release cycle

We regularly update dependencies to address security vulnerabilities. However, you should:

• Keep your dependencies up to date
• Review security advisories for our dependencies
• Use tools like pip-audit or safety to check for known vulnerabilities

• Never commit API keys or credentials to the repository
• Use environment variables or secure configuration management
• Rotate keys regularly
• Use least-privilege access principles

• Be cautious when processing untrusted data
• Validate and sanitize all inputs
• Use parameterized queries for database operations
• Implement rate limiting for public APIs

• Use HTTPS for all network communications
• Validate SSL/TLS certificates
• Be cautious with external API calls
• Implement proper authentication and authorization

Semantica's build and release pipeline is explicitly hardened against CI/CD supply-chain attacks — the class of attack behind the March 2026 LiteLLM/Trivy incident, where a compromised third-party Action with a mutable tag was used to steal a long-lived publishing token, after which malicious packages were pushed straight to PyPI without ever touching the source repository. Every control below maps directly to closing one step of that attack chain.

• Risk: a tag (@v4, @release/v1) is re-pointed by a compromised upstream maintainer or account, silently changing what every consumer's CI runs. Control: every third-party GitHub Action in every workflow is pinned to a full 40-character commit SHA, with the human-readable tag kept only as a trailing comment (e.g. actions/checkout@3d3c42e... # v7).
• Risk: a SHA pin drifts out of sync with its own comment over time, or is mistyped. Control: verify-action-pins.yml fails closed on any uses: reference that isn't a full commit SHA (catching a newly added mutable tag, not just auditing existing pins), resolves every pinned tag via the GitHub API on each workflow change, on every push to main, and weekly, and fails if the SHA no longer matches the tag it claims to be — an API lookup that can't be resolved is treated as a failure, not a silent skip.
• Risk: manually re-pinning ~15 actions across 8 workflow files on every upstream release is error-prone. Control: Dependabot (github-actions ecosystem) opens a grouped PR that bumps the SHA and the tag comment together whenever an action releases — pins never require hand-editing.

• Risk: a long-lived PYPI_TOKEN sitting in repo/org secrets is exfiltrated by any compromised step. Control: PyPI publishing uses Trusted Publishing (OIDC) (id-token: write) — there is no long-lived PyPI credential anywhere in this repository to steal.
• Risk: a compromised CI run publishes to PyPI with no human in the loop. Control: the publish job runs only inside a protected pypi GitHub Environment with a required human reviewer — every release needs manual approval in the Actions UI before it runs.
• Risk: the release job could be triggered from an arbitrary branch/ref. Control: the pypi environment's deployment-branch policy is restricted to v* tags only.
• Risk: a scanner or unrelated job inherits publish-level credentials. Control: release.yml sets permissions: contents: read at the workflow level; contents: write / id-token: write / attestations: write are granted only to the release job, never workflow-wide.
• Risk: two tag pushes race through the publish pipeline simultaneously. Control: concurrency: group: release-${{ github.ref }} serializes releases per tag.
• Risk: a consumer can't verify a wheel on PyPI actually came from this repo's CI. Control: SLSA build provenance is attested for every release via actions/attest-build-provenance, producing a signed, verifiable record of the exact commit and workflow run that produced the artifact (checkable with gh attestation verify).

• Risk: unreviewed or force-pushed changes land on main. Control: main requires 1 approving PR review (stale approvals dismissed on new pushes), resolved conversations, and blocks force-pushes and branch deletion.
• Risk: a PR merges without its security/CI checks passing. Control: merges require the build, Analyze Python (CodeQL), and security-scan checks to pass, in strict mode (checks must be re-run against the latest main).
• Risk: a compromised scanner job reaches secrets or write access. Control: scanning jobs (CodeQL, security-scan.yml, security.yml, defender-for-devops.yml) run with read-only, least-privilege permissions (typically contents: read + security-events: write only) and never share a job, environment, or secret scope with the publish job.
• Risk: secrets are committed accidentally. Control: GitHub secret scanning and push protection are both enabled at the repository level, rejecting pushes that contain recognizable credential patterns before they land in history.

Every scan below runs continuously in CI, not just at release time:

• CodeQL (security-and-quality query pack) — Python source: injection, unsafe deserialization, and other code-level vulnerability classes. Runs in codeql.yml on every push/PR to main and weekly.
• Bandit — Python-specific security anti-patterns (hardcoded secrets, unsafe eval/pickle, weak crypto, etc.); CI fails on any HIGH-severity finding. Runs in security-scan.yml on every push/PR to main and twice weekly.
• Semgrep (p/security ruleset) — cross-language static-analysis security patterns. Runs in security-scan.yml on every push/PR to main and twice weekly.
• Safety — known CVEs in Semantica's own installed dependencies, including optional LLM-provider extras such as LiteLLM; CI fails on any match. Runs in security-scan.yml on every push/PR to main and twice weekly.
• pip-audit — independent, PyPA-maintained vulnerability database cross-check against installed dependencies (Safety and pip-audit use different advisory sources, so both run). Runs in security.yml weekly.
• Microsoft Defender for DevOps (eslint, templateanalyzer, terrascan) — JavaScript/TypeScript lint-security rules and infrastructure-as-code misconfigurations. Runs in defender-for-devops.yml on every push/PR to main and weekly.
• Checkov — Kubernetes, Helm, Dockerfile, GitHub Actions, and secrets-pattern IaC scanning; results upload to the same Security tab as CodeQL. Runs in defender-for-devops.yml on every push/PR to main and weekly.
• GitGuardian — secret-detection check on every pull request, installed as a GitHub App integration (not a repo-local workflow). Runs on every PR.
• GitHub secret scanning + push protection — blocks known credential patterns before they're pushed, and continuously scans existing history. Platform-level, continuous.
• Dependabot — version/security PRs for Python, Docker, and GitHub Actions dependencies, grouped where relevant to reduce review noise. Configured in .github/dependabot.yml, runs weekly for security-relevant packages and monthly for docs dependencies.
• verify-action-pins.yml — enforces that every Action reference is a full commit SHA (failing on a newly introduced mutable tag) and confirms each SHA still matches the tag it claims to be. Runs on every workflow change, every push to main, and weekly.

All SARIF-producing scanners (CodeQL, Checkov, Microsoft Defender) publish findings to the repository's Security → Code scanning alerts tab, giving a single audit trail across tools rather than scattered per-tool reports.

Teams standing up their own instance of Semantica, or forking it for an internal/regulated deployment, can reuse this posture directly:

1. Keep Dependabot's github-actions ecosystem entry — it is what keeps SHA pins current without manual maintenance.
2. Re-run verify-action-pins.yml after re-pointing the repository's Actions at your own mirrors, if you do so.
3. If you publish your own PyPI package from a fork, configure your own Trusted Publishing trust relationship on PyPI (Trusted Publishing is scoped to a specific owner/repo + workflow filename) and your own protected environment with your own required reviewers — these are not transferable from this repository.
4. Branch protection, environment protection, and repository secret scanning are repository settings, not workflow files — cloning or forking the repo does not copy them. They must be re-applied via the GitHub UI or API on the new repository.
5. GitHub secret scanning and push protection are repository settings that don't carry over to a fork either — re-enable both under the new repository's Security settings, not just Dependabot.
6. GitGuardian runs as a GitHub App installation scoped to this specific repository, not a workflow file — a fork gets no secret-detection coverage from it until the app is installed separately on the new repo.
7. CodeQL's upload-sarif step in codeql.yml only runs meaningfully if Default Setup is not already enabled for the repository (it's designed to skip gracefully otherwise) — check whether Default Setup or Advanced Setup is active on the new repository and adjust expectations for where CodeQL findings show up accordingly.

• We monitor security advisories for all dependencies
• We update dependencies regularly in our development branch
• Critical security updates are backported to supported versions

If you discover a vulnerability in one of our dependencies:

1. Check if it's already reported upstream
2. Report to us if it affects Semantica specifically
3. We will coordinate with upstream maintainers if needed

We use automated tools to scan for vulnerabilities:

• Dependabot: Automated dependency updates and security alerts
• GitHub Security Advisories: Vulnerability tracking
• Manual Reviews: Regular security audits

1. Keep Semantica Updated: Always use the latest stable version
2. Review Dependencies: Regularly update your project dependencies
3. Secure Configuration: Use secure defaults and proper configuration
4. Monitor Logs: Watch for suspicious activity
5. Report Issues: Don't hesitate to report potential security issues

We appreciate responsible disclosure. Security researchers who help us improve the security of Semantica will be:

• Credited in security advisories (if desired)
• Listed in our security acknowledgments
• Recognized for their contribution

For security-related questions or concerns:

• Private Reporting: Please do not report vulnerabilities in public issues.
• GitHub Security Advisories: Report vulnerability

• OWASP Top 10
• Python Security Best Practices
• GitHub Security Best Practices

Thank you for helping keep Semantica and its users safe!