diff --git a/.github/workflows/rust-audit-security.yml b/.github/workflows/rust-audit-security.yml new file mode 100644 index 0000000..27d77cc --- /dev/null +++ b/.github/workflows/rust-audit-security.yml @@ -0,0 +1,35 @@ +name: 'Rust Security Audit' +on: + workflow_call: + inputs: + ignore-advisories: + description: 'Comma-separated advisory IDs to ignore (e.g., RUSTSEC-2021-0001,RUSTSEC-2021-0002)' + required: false + default: '' + type: string + working-directory: + description: 'Directory containing Cargo.toml' + required: false + default: '.' + type: string + +permissions: + contents: read + issues: write + checks: write + +jobs: + security-audit: + name: Security Audit + runs-on: + group: init4-runners + steps: + - name: Checkout repository + uses: actions/checkout@v6 + + - name: Run security audit + uses: rustsec/audit-check@v2.0.0 + with: + token: ${{ github.token }} + ignore: ${{ inputs.ignore-advisories }} + working-directory: ${{ inputs.working-directory }} diff --git a/docs/rust-audit-security.md b/docs/rust-audit-security.md new file mode 100644 index 0000000..9345036 --- /dev/null +++ b/docs/rust-audit-security.md @@ -0,0 +1,205 @@ +# rust-audit-security.yml + +## Base Usage + +```yml +rust-security: + uses: init4tech/actions/.github/workflows/rust-audit-security.yml@main +``` + +This workflow uses the official [rustsec/audit-check](https://github.com/rustsec/audit-check) action to check for security vulnerabilities in your Rust dependencies. When vulnerabilities are found on scheduled runs, it automatically creates GitHub issues with detailed information about each advisory. + +## Features + +- **Automatic Issue Creation**: Creates GitHub issues for each security advisory (on scheduled runs only) +- **Deduplication**: Checks for existing issues to avoid duplicates +- **Check Creation**: Creates status checks on push/PR events that fail when vulnerabilities are found +- **Advisory Filtering**: Ignore specific advisories when needed +- **Official Maintenance**: Maintained by the RustSec team +- **Flexible Scheduling**: Run on a schedule, on push, or manually + +## Optional Parameters + +### `ignore-advisories` + +**Description:** Comma-separated advisory IDs to ignore. Useful for accepting known risks or false positives. + +**Type**: `string` + +**Default Value:** `''` (empty string, no advisories ignored) + +**Allowed values:** Advisory IDs from RustSec database (e.g., `RUSTSEC-2021-0001,RUSTSEC-2021-0002`) + +### `working-directory` + +**Description:** Directory containing `Cargo.toml`. Useful for monorepos or non-root projects. + +**Type**: `string` + +**Default Value:** `.` (repository root) + +**Allowed values:** Any valid directory path relative to repository root + +## Scheduling Recommendations + +This workflow is designed to run on a schedule to continuously monitor your dependencies for security vulnerabilities. + +### Daily Check (Recommended for Active Projects) + +```yml +on: + schedule: + - cron: '0 9 * * *' # 9 AM UTC daily + workflow_dispatch: # Allow manual runs +``` + +### Weekly Check (Recommended for Most Projects) + +```yml +on: + schedule: + - cron: '0 9 * * 1' # 9 AM UTC every Monday + workflow_dispatch: # Allow manual runs +``` + +### Monthly Check (Low-Risk Projects) + +```yml +on: + schedule: + - cron: '0 9 1 * *' # 9 AM UTC on the 1st of each month + workflow_dispatch: # Allow manual runs +``` + +## Behavior + +### On Push/Pull Request + +The workflow creates a status check that fails when vulnerabilities are found. Informational advisories do not affect the check status. + +### On Scheduled Runs + +The workflow automatically creates GitHub issues for each new advisory discovered, including informational ones. + +### Issue Format + +Created issues follow this format (generated by rustsec/audit-check): + +**Title**: `RUSTSEC-YYYY-NNNN: Advisory Title` + +**Body**: A markdown table with package name, version, patched versions, URL, date, and the full advisory description. + +### Deduplication + +The workflow automatically checks for existing issues/PRs with the same advisory ID in the title before creating new issues. This prevents duplicate issues on subsequent runs. + +### Managing False Positives + +If an advisory does not apply to your usage or you accept the risk, you have two options: + +1. **Close the issue**: Simply close the GitHub issue. The workflow will not recreate it as long as it exists (even when closed). + +2. **Ignore the advisory**: Add the advisory ID to the `ignore-advisories` parameter. This prevents the workflow from reporting the advisory at all. + +```yml +with: + ignore-advisories: 'RUSTSEC-2021-0001,RUSTSEC-2023-0042' +``` + +## Example Configurations + +### Basic Configuration with Scheduling + +```yml +name: Security Audit +on: + schedule: + - cron: '0 9 * * 1' # Weekly on Monday + workflow_dispatch: + +permissions: + contents: read + issues: write + checks: write + +jobs: + security-audit: + uses: init4tech/actions/.github/workflows/rust-audit-security.yml@main +``` + +### On Push to Main + +```yml +name: Security Audit +on: + push: + branches: [main] + paths: + - '**/Cargo.toml' + - '**/Cargo.lock' + +permissions: + contents: read + checks: write + +jobs: + security-audit: + uses: init4tech/actions/.github/workflows/rust-audit-security.yml@main +``` + +### Monorepo Configuration + +```yml +jobs: + security-audit-api: + uses: init4tech/actions/.github/workflows/rust-audit-security.yml@main + with: + working-directory: './packages/api' + + security-audit-cli: + uses: init4tech/actions/.github/workflows/rust-audit-security.yml@main + with: + working-directory: './packages/cli' +``` + +### Ignoring Known Issues + +```yml +jobs: + security-audit: + uses: init4tech/actions/.github/workflows/rust-audit-security.yml@main + with: + ignore-advisories: 'RUSTSEC-2020-0071,RUSTSEC-2021-0145' +``` + +## Permissions Required + +The workflow requires the following GitHub token permissions: + +- `contents: read` - To checkout the repository +- `issues: write` - To create and check issues (required for scheduled runs) +- `checks: write` - To create status checks (required for push/PR runs) + +These permissions must be set in the calling workflow: + +```yml +# For scheduled runs (creates issues) +permissions: + contents: read + issues: write + checks: write + +# For push/PR runs (creates checks only) +permissions: + contents: read + checks: write +``` + +## Notes + +- Issues are **only created on scheduled runs**, not on push or pull request events +- On push/PR events, the workflow creates status checks that fail when vulnerabilities are found +- Informational advisories do not affect check status but do create issues on scheduled runs +- The workflow uses the official [rustsec/audit-check](https://github.com/rustsec/audit-check) action maintained by the RustSec team +- Deduplication is handled automatically by checking for existing issues/PRs with the advisory ID +- The workflow cannot create checks for pull requests from forked repositories due to GitHub token permission restrictions diff --git a/examples/example-rust-audit-security.yml b/examples/example-rust-audit-security.yml new file mode 100644 index 0000000..8e5ffd0 --- /dev/null +++ b/examples/example-rust-audit-security.yml @@ -0,0 +1,29 @@ +name: Security Audit +# This workflow uses rustsec/audit-check to check for security vulnerabilities +# On scheduled runs: automatically creates GitHub issues for findings +# On push/PR: creates status checks that fail when vulnerabilities are found + +on: + schedule: + # Run every Monday at 9 AM UTC + - cron: '0 9 * * 1' + push: + branches: [main] + paths: + - '**/Cargo.toml' + - '**/Cargo.lock' + workflow_dispatch: # Allow manual runs + +permissions: # these permissions are required for the workflow to run + contents: read # Required to checkout the repository + issues: write # Required to create issues (scheduled runs) + checks: write # Required to create status checks (push/PR) + +jobs: + security-audit: + uses: init4tech/actions/.github/workflows/rust-audit-security.yml@main + # Optional: ignore specific advisories + # with: + # ignore-advisories: 'RUSTSEC-2020-0071,RUSTSEC-2021-0001' + # Optional: for monorepos or non-root projects + # working-directory: './packages/api'