Agent Skills: Python Packaging Security Audit

Python Packaging Security Audit

Orchestrates a comprehensive pre-onboarding security evaluation of Python packages by dispatching three specialized sub-skills as parallel background agents. Each agent writes its report section to an individual file; the orchestrator reads all files and assembles the unified report.

Inputs

• repo_path (optional): Local filesystem path to an already-cloned repository
• package_name (optional): Python package name — the skill will locate and clone the repository
• hexora_results (optional): File path to pre-computed hexora JSON output (hexora-results.json). Forwarded to the python-packaging-static-audit sub-skill.
• binary_scan (optional): File path to pre-computed binary scanner JSON output (binary-scan.json). Forwarded to the python-packaging-binary-audit sub-skill.
• malcontent_results (optional): File path to pre-computed malcontent JSON output (malcontent-results.json). Forwarded to the python-packaging-binary-audit sub-skill.

At least one of repo_path or package_name must be provided. If repo_path is given and points to an existing directory, skip straight to Step 2. Otherwise, use package_name to discover and clone the repository.

When pre-computed scan inputs are provided, repo_path is still needed for triage context (reading source files to understand findings). Always use --depth 50 for cloning because the git-audit sub-skill runs its own git history commands and needs sufficient commit history.

Step 1: Resolve Repository

If you already have a local repository path, skip to Step 2.

Otherwise, use the python-packaging-source-finder skill to locate the upstream repository URL:

Skill: python-packaging-source-finder
Args: <package_name>

If the skill returns a URL with high or medium confidence, clone it locally with enough history for the git scan:

CLONE_DIR=$(mktemp -d -t security-audit-XXXXXX)
git clone --depth 50 -- "<repository_url>" "$CLONE_DIR/repo"

Use $CLONE_DIR/repo as the repo path for Step 2.

If source-finder returns low confidence or no URL, stop and return a report with risk rating needs_review stating that the source repository could not be located.

Step 2: Dispatch Parallel Audits

Create a working directory for the report files:

AUDIT_DIR=$(mktemp -d -t security-audit-results-XXXXXX)

Dispatch three background agents in parallel. Each agent invokes one sub-skill and writes its findings to an individual file. The orchestrator does not need the intermediate reasoning context — only the final report sections matter.

When pre-computed scan inputs are available, forward them to the corresponding sub-skill so it skips tool execution and goes straight to triage.

Agent 1 — Static Analysis:

Dispatch a background Agent that invokes the python-packaging-static-audit skill
with repo_path=<repo-path> and output_file=$AUDIT_DIR/static-audit.md.
If hexora_results is provided, also pass hexora_results=<path>.
Then exits.

Agent 2 — Binary Scan:

Dispatch a background Agent that invokes the python-packaging-binary-audit skill
with repo_path=<repo-path> and output_file=$AUDIT_DIR/binary-audit.md.
If binary_scan is provided, also pass binary_scan=<path>.
If malcontent_results is provided, also pass malcontent_results=<path>.
Then exits.

Agent 3 — Git History:

Dispatch a background Agent that invokes the python-packaging-git-audit skill
with repo_path=<repo-path> and output_file=$AUDIT_DIR/git-audit.md, then exits.

Wait for all three agents to complete before proceeding.

Step 3: Combine Results

Read each output file. The first line of each file contains RISK_RATING:<value>. Extract the risk rating and the markdown report section from each file.

If a file is missing or empty, treat that phase as risk_rating = needs_review and state in the report section that the sub-skill did not produce output.

Assign the overall risk rating as the worst (most severe) rating across all phases:

• no_issues — All sub-skills returned no_issues
• low_risk — Worst sub-skill rating is low_risk
• needs_review — At least one sub-skill returned needs_review
• critical — At least one sub-skill returned critical

Precedence: critical > needs_review > low_risk > no_issues

Step 4: Cleanup

Clean up temporary directories:

rm -rf -- "${AUDIT_DIR}"

if [ -n "${CLONE_DIR}" ] && [[ "${CLONE_DIR}" == "${TMPDIR:-/tmp}"/* ]]; then
  rm -rf -- "${CLONE_DIR}"
else
  echo "ERROR: refusing to delete '${CLONE_DIR}' -- not under temp dir" >&2
fi

Output Format

Produce the following markdown report. When there are no findings, collapse to just the header, risk rating (no_issues), summary, and a statement that no issues were found.

# Security Assessment: {package-name}

**Risk Rating:** {no_issues | low_risk | needs_review | critical}
**Summary:** {1-2 sentence summary}

{Hexora Static Analysis section from static-audit.md}

{Binary Scan section from binary-audit.md}

{Git History Analysis section from git-audit.md}

## Recommendations

- {Bulleted list of specific actions based on findings across all phases}

Error Handling

Never abort the audit because a single tool is missing. Each sub-skill handles missing tools (hexora, malcontent) by returning a degraded report section with risk_rating = needs_review instead of failing. The orchestrator must always dispatch all three agents and combine whatever results are available.

| Scenario | Behavior | |----------|----------| | Source-finder returns low confidence or no URL | Stop; report needs_review stating source repo could not be located | | git clone fails | Stop; report needs_review stating repo could not be cloned | | A sub-skill output file is missing or empty | Include a note in that section; treat that phase as needs_review | | A sub-skill reports tool unavailable | Include its degraded output in the report; treat that phase as needs_review | | All sub-skills return no_issues | Report overall no_issues |