From 6000c0bbe9eda648947c7d9c104f255d06bda9f0 Mon Sep 17 00:00:00 2001 From: oh4 <7767846+iamteedoh@users.noreply.github.com> Date: Mon, 13 Jul 2026 20:36:38 -0400 Subject: [PATCH] IN-140: OSS repo standards; align README license and prerequisites --- .github/ISSUE_TEMPLATE/bug_report.yml | 79 +++++++++++++++ .github/ISSUE_TEMPLATE/config.yml | 8 ++ .github/ISSUE_TEMPLATE/feature_request.yml | 31 ++++++ .github/pull_request_template.md | 23 +++++ .github/workflows/ci.yml | 108 +++++++++++++++++++++ .github/workflows/release-please.yml | 27 ++++++ .gitignore | 9 ++ .gitleaks.toml | 8 ++ .release-please-manifest.json | 3 + CHANGELOG.md | 10 ++ CODE_OF_CONDUCT.md | 107 ++++++++++++++++++++ CONTRIBUTING.md | 69 +++++++++++++ README.md | 21 +++- SECURITY.md | 42 ++++++++ dirPathPerms.sh | 1 + release-please-config.json | 11 +++ 16 files changed, 552 insertions(+), 5 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/bug_report.yml create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/ISSUE_TEMPLATE/feature_request.yml create mode 100644 .github/pull_request_template.md create mode 100644 .github/workflows/ci.yml create mode 100644 .github/workflows/release-please.yml create mode 100644 .gitignore create mode 100644 .gitleaks.toml create mode 100644 .release-please-manifest.json create mode 100644 CHANGELOG.md create mode 100644 CODE_OF_CONDUCT.md create mode 100644 CONTRIBUTING.md create mode 100644 SECURITY.md create mode 100644 release-please-config.json diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..33b586c --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,79 @@ +name: Bug report +description: Report a reproducible dirPathPerms problem +labels: ["bug"] +body: + - type: markdown + attributes: + value: | + Thanks for reporting a problem. Do not paste tokens, passwords, + SSH keys, or private host details, and redact sensitive paths. + + - type: input + id: version + attributes: + label: dirPathPerms version + description: Provide a release tag or commit SHA. + placeholder: v0.1.0 or 0123456 + validations: + required: true + + - type: dropdown + id: component + attributes: + label: Component + options: + - Interactive prompts or input validation + - Permission checking logic + - Output formatting or colors + - Input file handling + - CI or release automation + - Documentation + validations: + required: true + + - type: dropdown + id: platform + attributes: + label: Platform + options: + - Linux (GNU coreutils) + - macOS + - Windows Subsystem for Linux (WSL) + - BSD or other Unix + - Not platform-specific + validations: + required: true + + - type: textarea + id: environment + attributes: + label: Environment + description: Include the OS, Bash version (`bash --version`), and `stat --version` output. Redact private details. + validations: + required: true + + - type: textarea + id: what-happened + attributes: + label: What happened? + description: Describe the observed and expected behavior. + validations: + required: true + + - type: textarea + id: reproduction + attributes: + label: Steps to reproduce + placeholder: | + 1. Run ... + 2. Observe ... + 3. Expected ... + validations: + required: true + + - type: textarea + id: logs + attributes: + label: Relevant redacted output + description: Remove secrets and private infrastructure details before pasting. + render: shell diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..c86c46a --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,8 @@ +blank_issues_enabled: false +contact_links: + - name: Security vulnerability + url: https://github.com/iamteedoh/dirPathPerms/security/advisories/new + about: Report security issues privately, not as public issues. + - name: Question or discussion + url: https://github.com/iamteedoh/dirPathPerms/discussions + about: Ask usage questions and discuss ideas with the community. diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..c505479 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,31 @@ +name: Feature request +description: Suggest a dirPathPerms improvement +labels: ["enhancement"] +body: + - type: textarea + id: problem + attributes: + label: Problem or motivation + description: What permission-auditing task is difficult today? + validations: + required: true + + - type: textarea + id: proposal + attributes: + label: Proposed solution + description: Describe the desired behavior, prompts, or output. + validations: + required: true + + - type: textarea + id: safety + attributes: + label: Safety considerations + description: Note anything that would change the script from read-only reporting, affect how untrusted paths are handled, or alter output parsing. + + - type: textarea + id: alternatives + attributes: + label: Alternatives considered + description: Describe other approaches or workarounds you considered. diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..c8c0a6c --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,23 @@ + + +## What does this PR do? + + + +## Related issue + + + +## Validation + + + +## Checklist + +- [ ] `git ls-files '*.sh' | xargs shellcheck` passes +- [ ] `git ls-files '*.sh' | xargs -n1 bash -n` passes +- [ ] gitleaks reports no secrets in Git history +- [ ] Scripts and programs include a GPL-3.0-or-later SPDX header +- [ ] No secrets, tokens, credentials, or private infrastructure details are committed +- [ ] Documentation is updated for user-visible or operational changes +- [ ] The PR title follows Conventional Commits diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..741c697 --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,108 @@ +--- +## Author: Tito Valentin +## Name of Program: dirPathPerms Continuous Integration +## Date Created: 2026-07-13 +## Description: Validates source quality, secrets, and OSS release requirements. +name: CI + +on: + push: + branches: [main] + pull_request: + +permissions: + contents: read + +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + +jobs: + lint-test: + name: Lint & test + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v7 + with: + persist-credentials: false + + - name: Run ShellCheck + run: git ls-files '*.sh' | xargs shellcheck + + - name: Check Bash syntax + run: git ls-files '*.sh' | xargs -n1 bash -n + + secrets: + name: Secret scan + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v7 + with: + fetch-depth: 0 + persist-credentials: false + + - name: Install gitleaks + env: + GITLEAKS_VERSION: 8.30.1 + GITLEAKS_SHA256: 551f6fc83ea457d62a0d98237cbad105af8d557003051f41f3e7ca7b3f2470eb + run: | + archive="gitleaks_${GITLEAKS_VERSION}_linux_x64.tar.gz" + curl -sSfLo "/tmp/${archive}" \ + "https://github.com/gitleaks/gitleaks/releases/download/v${GITLEAKS_VERSION}/${archive}" + echo "${GITLEAKS_SHA256} /tmp/${archive}" | sha256sum --check + tar -xzf "/tmp/${archive}" -C /tmp gitleaks + + - name: Scan the full Git history + run: /tmp/gitleaks git . --config .gitleaks.toml --redact --no-banner + + community-files: + name: OSS community & licensing files + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v7 + with: + persist-credentials: false + + - name: Require community health and licensing files + shell: bash + run: | + fail=0 + require() { + if [ ! -s "$1" ]; then + echo "::error::missing or empty: $1" + fail=1 + fi + } + + require LICENSE + require README.md + require CONTRIBUTING.md + require CODE_OF_CONDUCT.md + require SECURITY.md + require CHANGELOG.md + require .github/FUNDING.yml + require .github/pull_request_template.md + require .github/ISSUE_TEMPLATE/bug_report.yml + require .github/ISSUE_TEMPLATE/feature_request.yml + + if ! grep -q "GNU GENERAL PUBLIC LICENSE" LICENSE \ + || ! grep -q "Version 3" LICENSE; then + echo "::error::LICENSE is not GNU GPL v3" + fail=1 + fi + + if ! grep -qE '^\s*(github|patreon|open_collective|ko_fi|buy_me_a_coffee|liberapay|custom):' \ + .github/FUNDING.yml; then + echo "::error::.github/FUNDING.yml has no sponsor or payment link" + fail=1 + fi + + while IFS= read -r file; do + if ! head -n 8 "$file" | grep -q 'SPDX-License-Identifier: GPL-3.0-or-later'; then + echo "::error file=${file}::missing GPL-3.0-or-later SPDX header" + fail=1 + fi + done < <(git ls-files '*.sh') + + [ "$fail" -eq 0 ] || exit 1 + echo "All required OSS community and licensing checks passed." diff --git a/.github/workflows/release-please.yml b/.github/workflows/release-please.yml new file mode 100644 index 0000000..8ccf0c3 --- /dev/null +++ b/.github/workflows/release-please.yml @@ -0,0 +1,27 @@ +--- +## Author: Tito Valentin +## Name of Program: dirPathPerms Release Automation +## Date Created: 2026-07-13 +## Description: Creates source-only releases from Conventional Commit history. +name: release-please + +# dirPathPerms is distributed as source. Merging the generated release PR +# updates the changelog and version marker, creates a vX.Y.Z tag, and publishes +# a GitHub Release. There is intentionally no binary build or artifact upload. +on: + push: + branches: [main] + +permissions: + contents: write + issues: write + pull-requests: write + +jobs: + release-please: + runs-on: ubuntu-latest + steps: + - uses: googleapis/release-please-action@v5 + with: + config-file: release-please-config.json + manifest-file: .release-please-manifest.json diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..8836b68 --- /dev/null +++ b/.gitignore @@ -0,0 +1,9 @@ +# Environment files +.env + +# OS artifacts +.DS_Store + +# Editor artifacts +*.swp +*.swo diff --git a/.gitleaks.toml b/.gitleaks.toml new file mode 100644 index 0000000..b459146 --- /dev/null +++ b/.gitleaks.toml @@ -0,0 +1,8 @@ +## Author: Tito Valentin +## Name of Program: dirPathPerms Gitleaks Configuration +## Date Created: 2026-07-13 +## Description: Extends the default Gitleaks rules for repository history scans. +title = "dirPathPerms gitleaks configuration" + +[extend] +useDefault = true diff --git a/.release-please-manifest.json b/.release-please-manifest.json new file mode 100644 index 0000000..e18ee07 --- /dev/null +++ b/.release-please-manifest.json @@ -0,0 +1,3 @@ +{ + ".": "0.0.0" +} diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..babff0f --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,10 @@ +# Changelog + +All notable changes to dirPathPerms are documented here. + +This project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +Release entries are maintained by release-please from Conventional Commit PR +titles merged into `main`. + +There are no tagged releases yet. The first releasable `feat:` or `fix:` change +will prepare the initial source release. diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..5aeeb64 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,107 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +We as members, contributors, and leaders pledge to make participation in our +community a harassment-free experience for everyone, regardless of age, body +size, visible or invisible disability, ethnicity, sex characteristics, gender +identity and expression, level of experience, education, socio-economic +status, nationality, personal appearance, race, caste, color, religion, or +sexual identity and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, +diverse, inclusive, and healthy community. + +## Our Standards + +Examples of behavior that contributes to a positive environment include: + +- Demonstrating empathy and kindness toward other people +- Being respectful of differing opinions, viewpoints, and experiences +- Giving and gracefully accepting constructive feedback +- Accepting responsibility and apologizing to those affected by mistakes, and + learning from the experience +- Focusing on what is best for the overall community + +Examples of unacceptable behavior include: + +- Sexualized language or imagery, and sexual attention or advances of any kind +- Trolling, insulting or derogatory comments, and personal or political attacks +- Public or private harassment +- Publishing others' private information without explicit permission +- Other conduct that could reasonably be considered inappropriate in a + professional setting + +## Enforcement Responsibilities + +Community leaders are responsible for clarifying and enforcing these standards +and will take appropriate and fair corrective action in response to behavior +they deem inappropriate, threatening, offensive, or harmful. + +Community leaders have the right and responsibility to remove, edit, or reject +comments, commits, code, wiki edits, issues, and other contributions that are +not aligned with this Code of Conduct, and will communicate moderation reasons +when appropriate. + +## Scope + +This Code of Conduct applies within all community spaces and when an individual +is officially representing the community in public spaces. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported through GitHub's private reporting on this repository or through the +maintainer profile at https://github.com/iamteedoh. Complaints will be reviewed +and investigated promptly and fairly. Community leaders must respect the +privacy and security of reporters. + +## Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines when +determining consequences for actions that violate this Code of Conduct. + +### 1. Correction + +**Community Impact**: Inappropriate language or behavior deemed unprofessional +or unwelcome. + +**Consequence**: A private written warning that explains the violation and why +the behavior was inappropriate. A public apology may be requested. + +### 2. Warning + +**Community Impact**: A violation through a single incident or series of +actions. + +**Consequence**: A warning with consequences for continued behavior. No +interaction with the people involved, including unsolicited interaction with +those enforcing the Code of Conduct, for a specified period. Violating these +terms may lead to a temporary or permanent ban. + +### 3. Temporary Ban + +**Community Impact**: A serious violation of community standards, including +sustained inappropriate behavior. + +**Consequence**: A temporary ban from community interaction or public +communication. Violating these terms may lead to a permanent ban. + +### 4. Permanent Ban + +**Community Impact**: A pattern of violations, sustained harassment, +aggression, or disparagement of individuals or classes of individuals. + +**Consequence**: A permanent ban from community interaction. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], +version 2.1, available at +https://www.contributor-covenant.org/version/2/1/code_of_conduct.html. + +Community Impact Guidelines were inspired by +[Mozilla's code of conduct enforcement ladder][Mozilla CoC]. + +[homepage]: https://www.contributor-covenant.org +[Mozilla CoC]: https://github.com/mozilla/diversity diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..c53fb22 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,69 @@ +# Contributing to dirPathPerms + +Thanks for helping improve dirPathPerms. This guide covers local setup, +validation, and the pull request process. + +## Ways to contribute + +- **Report a bug** using the repository's bug report form. +- **Request a feature** using the feature request form. +- **Send a pull request** after opening an issue for non-trivial changes. +- **Report a vulnerability privately** by following [SECURITY.md](SECURITY.md). + +## Prerequisites + +- Bash (the script targets `#!/bin/bash`) +- GNU coreutils `stat` (`stat -c '%A'`) to run the script itself — standard on + Linux; on macOS install coreutils or run inside a Linux environment +- `shellcheck` +- gitleaks 8.30.1 or newer + +## Set up from a clean clone + +```bash +git clone https://github.com/iamteedoh/dirPathPerms.git +cd dirPathPerms +chmod +x dirPathPerms.sh +``` + +No build step and no dependencies to install — the repository is a single +Bash script. Never commit secrets, tokens, credentials, or private +infrastructure details. + +## Run the validation suite + +Run the same checks that protect `main`: + +```bash +git ls-files '*.sh' | xargs shellcheck +git ls-files '*.sh' | xargs -n1 bash -n +gitleaks git . --config .gitleaks.toml --redact --no-banner +``` + +When changing script behavior, exercise the interactive flow locally against a +small sample paths file and confirm both the `YES`/`NO` output and the +missing-path handling still work. + +## Project layout + +- `dirPathPerms.sh` — the interactive permission checker script +- `.github/workflows/` — source validation and source-only release automation + +## Pull request process + +1. Create a branch from `main`. +2. Make the smallest complete change and update documentation. +3. Run the full validation suite above. +4. Use a [Conventional Commit](https://www.conventionalcommits.org/) PR title: + `feat:`, `fix:`, `docs:`, `refactor:`, `ci:`, `test:`, or `chore:`. +5. Complete the pull request template and link the related public issue. +6. Wait for all required checks to pass, then squash-merge. + +The PR title becomes the squash commit subject and drives release-please: +`fix:` creates a patch release, `feat:` creates a minor release, and a `!` or +`BREAKING CHANGE:` footer creates a breaking release. + +## License + +By contributing, you agree that your contributions are licensed under the +project's [GNU General Public License v3](LICENSE). diff --git a/README.md b/README.md index 05c567a..bbda899 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ [![GitHub Sponsors](https://img.shields.io/badge/Sponsor-GitHub-ea4aaa?logo=github)](https://github.com/sponsors/iamteedoh) [![Patreon](https://img.shields.io/badge/Support-Patreon-f96854?logo=patreon)](https://patreon.com/iamteedoh) [![Buy Me a Coffee](https://img.shields.io/badge/Buy%20Me%20a%20Coffee-FFDD00?logo=buymeacoffee&logoColor=black)](https://buymeacoffee.com/iamteedoh) -# dirPathsPerms +# dirPathPerms # File Permission Checker Script @@ -35,7 +35,10 @@ This script is useful for: * A Bash-compatible shell (standard on most Linux distributions and macOS). * Standard Unix/Linux command-line utilities, specifically: - * `stat` (used for retrieving file status, including permissions). + * GNU `stat` (used for retrieving file status, including permissions). The + script calls `stat -c '%A'`, which is GNU coreutils syntax — standard on + Linux. On macOS/BSD, install GNU coreutils and make sure its `stat` comes + first on your `PATH` (for Homebrew, the `gnubin` directory). * `read`, `echo`, `printf` (standard shell built-ins). ## Installation @@ -88,7 +91,7 @@ Let's say you want to check if members of the owning **Group** have **Write** ac * `/etc/passwd ` : `-rw-r--r--` (Owner: rw, Group: r, Other: r) * `/home/user/important_script.sh` : `-rwxr-x---` (Owner: rwx, Group: rx, Other: ---) -* `/var/log/app.log` : `-rw-wr----` (Owner: rw, Group: rw, Other: ---) +* `/var/log/app.log` : `-rw-rw----` (Owner: rw, Group: rw, Other: ---) * `/tmp` : `drwxrwxrwt` (Owner: rwx, Group: rwx, Other: rwt - sticky bit) * `/non/existent/path` : Does not exist * `/data/shared_folder` : `drwxrwx---` (Owner: rwx, Group: rwx, Other: ---) @@ -148,6 +151,14 @@ Skipping: /non/existent/path (Not a file or directory) ## License -This script is provided as-is. You can consider it under the MIT License or use it freely as needed. +This project is licensed under the [GNU General Public License v3](LICENSE). -This `README.md` file covers the script's purpose, usage, input/output details, and provides a clear example to help users understand how to use it effectively. +## Contributing + +Contributions are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) for local +setup, the validation suite, and the pull request process. + +## Security + +Please report vulnerabilities privately as described in +[SECURITY.md](SECURITY.md), not through public issues. diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..63d870d --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,42 @@ +# Security Policy + +## Reporting a vulnerability + +**Do not report security vulnerabilities through public GitHub issues.** + +Use GitHub's private vulnerability reporting instead: + +1. Open the repository's **Security** tab. +2. Select **Report a vulnerability**. +3. Provide the details requested below. + +If private reporting is unavailable, contact the maintainer through the +[iamteedoh GitHub profile](https://github.com/iamteedoh). + +## What to include + +- A description of the issue and its potential impact +- Reproduction steps or a minimal proof of concept +- The affected release, commit, platform, and component +- A suggested remediation, if known + +Never include live bearer tokens, passwords, SSH keys, private hostnames, or +unredacted logs in a report. + +## Security-sensitive areas + +dirPathPerms is a read-only auditing script, so the most sensitive surfaces +are: + +- Handling of the user-supplied input file and the paths read from it + (quoting, word splitting, and paths that point at symlinks or special files) +- Terminal output built from filesystem paths, including the `printf` format + strings and ANSI color escape sequences +- Any future change that would make the script modify permissions instead of + only reporting them +- CI and release automation workflows + +## Supported versions + +Security fixes land on `main` and ship in the next tagged source release. Test +against the latest release or `main` before reporting an issue. diff --git a/dirPathPerms.sh b/dirPathPerms.sh index c293302..83954ec 100755 --- a/dirPathPerms.sh +++ b/dirPathPerms.sh @@ -1,4 +1,5 @@ #!/bin/bash +# SPDX-License-Identifier: GPL-3.0-or-later # Function to wrap long lines fold() { diff --git a/release-please-config.json b/release-please-config.json new file mode 100644 index 0000000..cec6298 --- /dev/null +++ b/release-please-config.json @@ -0,0 +1,11 @@ +{ + "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json", + "release-type": "simple", + "bump-minor-pre-major": true, + "bootstrap-sha": "b5fe6230d5f86481eb76d4dad58e174f4cfa3c2d", + "packages": { + ".": { + "package-name": "dirPathPerms" + } + } +}