microsoft / microsoft/hve-core

docs: document pip-audit-known-vulnerabilities.txt suppression file for Python skills

Open
#1,628 0 comments 0 reactions 1 assignee Claimed by @tomomi-code View on GitHub
agent-ready documentation needs-triage
Dominant language
Python
Stars
1.5k
Forks
301
Avg merge
3d 3h
Merged PRs (30d)
92

Description

## Component

Documentation

## Bug Description

The `pip-audit.yml` workflow supports a per-skill `pip-audit-known-vulnerabilities.txt` file that allows skill maintainers to suppress acknowledged vulnerability IDs (e.g., `PYSEC-2025-183`). This mechanism is used in `.github/skills/experimental/tts-voiceover/pip-audit-known-vulnerabilities.txt` (added in #1627) but is not documented in the contributing or customization skills guides.

The workflow reads this file from the skill's working directory, strips comment lines (prefixed with `#`), and passes each remaining ID to `pip-audit --ignore-vuln`. This is an important safety valve for disputed or accepted findings, but contributors have no way to discover it exists.

## Expected Behavior

`docs/contributing/skills.md` and/or `docs/customization/skills.md` should document:

- The `pip-audit-known-vulnerabilities.txt` file name and its placement at the skill root.
- The file format: one vulnerability ID per line (e.g., `PYSEC-2025-183`), comments prefixed with `#`.
- Guidance on when to use it: disputed upstream findings, accepted risk with justification comment.
- Note that each suppressed ID should include a `#` comment explaining the rationale and a revisit condition.

## Steps to Reproduce

1. Review PR #1627 which adds `.github/skills/experimental/tts-voiceover/pip-audit-known-vulnerabilities.txt`.
2. Search `docs/contributing/skills.md` and `docs/customization/skills.md` — no mention of this file or its format.
3. The workflow logic is in `.github/workflows/pip-audit.yml` lines 88–94.

## Additional Context

- Code file changed: `.github/skills/experimental/tts-voiceover/pip-audit-known-vulnerabilities.txt`
- Workflow implementing the feature: `.github/workflows/pip-audit.yml`
- Documentation files that need updating: `docs/contributing/skills.md`, `docs/customization/skills.md`

> Generated by [Documentation Update Check](https://github.com/microsoft/hve-core/actions/runs/26196009726) · ● 9.3M · [◷](https://github.com/search?q=repo%3Amicrosoft%2Fhve-core+is%3Aissue+%22gh-aw-workflow-call-id%3A+microsoft%2Fhve-core%2Fdoc-update-check%22&type=issues)

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.