From 9c7b92748470359ed87e69cb9f085c2cc6cd5cd6 Mon Sep 17 00:00:00 2001 From: "Danilo M." Date: Sun, 9 Aug 2026 19:06:10 +0200 Subject: docs: rename CLAUDE.md to AGENTS.md and update references --- .extras/hooks/pre-commit | 2 +- .gitignore | 1 + AGENTS.md | 489 ++++++++++++++++++++++++++++++++++++++++++++++ CLAUDE.md | 490 +---------------------------------------------- TODO.md | 2 +- 5 files changed, 493 insertions(+), 491 deletions(-) create mode 100644 AGENTS.md diff --git a/.extras/hooks/pre-commit b/.extras/hooks/pre-commit index 7158125..d7bbbc8 100755 --- a/.extras/hooks/pre-commit +++ b/.extras/hooks/pre-commit @@ -77,7 +77,7 @@ if [ "${SBOLINT:-yes}" = "yes" ]; then # the .SlackBuild: that's the build dir sbolint wants. Depth # isn't assumed, so this works for both a flat layout # (/) and SBo's own (//). Root-level - # files (CLAUDE.md, .extras/...) walk up to "." and are + # files (AGENTS.md, .extras/...) walk up to "." and are # dropped, they aren't builds. d=$(dirname "$f") while [ "$d" != "." ] && [ "$d" != "/" ]; do diff --git a/.gitignore b/.gitignore index d85e02c..fda1e69 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,5 @@ .claude +.agents SBo/ *.bak LAST_SWEEP diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..4fb25bb --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,489 @@ +# SBo SlackBuilds Repository + +SlackBuild scripts for which danix is the **official SBo maintainer** on +[SlackBuilds.org (SBo)](https://slackbuilds.org). + +## Purpose: tracking, not development + +This repo is a **maintenance mirror of already-published SBo packages**. No new +packages are developed here. Its job is the ongoing upkeep of packages already +on SBo: + +1. Track upstream version changes (via nvchecker). +2. Reflect a new upstream version in the package's `.SlackBuild` / `.info`. +3. Test-build with the `test-build` tool (see below). +4. Generate the SBo submission tarball to upload. + +New-package development happens in **other** repos, not here: + +- `../GITHUB/my-slackbuilds/` — regular packages, plus SBo packages whose + upstream moves faster than SBo review (worked ahead of the SBo copy). +- `../GITHUB/Slackware-Pentesting-Suite/` — cybersecurity packages. + +When a new package is uploaded to SBo and approved, it **moves here** and this +repo takes over its maintenance. + +--- + +## Repo Structure + +Packages live under their SBo category, mirroring the layout of the SBo repo +itself (`//`): + +``` +// +├── .SlackBuild # Main build script +├── .info # Metadata (version, checksums, URLs) +├── README # Description and usage notes +├── slack-desc # Package description (11-line format) +├── .desktop # (optional) Desktop entry for GUI apps +└── [...] # other optional files +``` + +The category is not recorded anywhere else: the directory *is* the category. +It is authoritative in the synced SBo tree, so to find where a package +belongs: + +```bash +find /var/lib/sbopkg/SBo-stable -maxdepth 2 -mindepth 2 -type d -name '' +``` + +Current categories: `misc` (SecLists, exploitdb, nuclei), `games` +(UrbanTerror), `network` (feroxbuster, ffuf, gobuster, +metasploit-framework-bin, r8125). + +Matching SBo's layout means a package directory exports to the SBo repo at +the identical relative path, with no mapping step. Both git hooks locate a +build by walking up to the directory holding the `.SlackBuild`, so neither +asserts a fixed depth. + +Version tracking is handled by a single file: + +``` +.extras/nvchecker.toml # nvchecker config listing all packages +``` + +### `.extras/` holds all non-package repo files + +Anything that is not a SlackBuild package must live under `.extras/`, never at +the repo root. Currently: `nvchecker.toml` (version tracking), `hooks/` (git +hooks), `assets/`. + +--- + +## Build Strategies + +Packages fall into several categories; the SlackBuild style differs +accordingly. + +### Source builds (Go) + +Packages such as `ffuf`, `gobuster`, `nuclei` are built from upstream source +tarballs using `go build`. Key points: + +- Set `GOPATH`, `GOPROXY`, `GOFLAGS` before building +- Use `-buildmode=pie -trimpath -mod=readonly -modcacherw` +- Strip ELF binaries after build +- Clean up `$GOPATH` / Go module cache before packaging +- `REQUIRES="google-go-lang"` in the `.info` file + +### Source builds (Rust) + +Packages such as `feroxbuster` build from a vendored crates tarball +(`--vendor.tar.gz`) declared as a second source in `.info`, +alongside the upstream tarball. The SlackBuild unpacks it, points cargo at it +via `.cargo/config.toml`, and builds fully offline (`cargo build --offline +--locked`). The vendor tarball is generated once per version with +`cargo-vendor-filterer`, with `SOURCE_DATE_EPOCH` pinned to the release tag's +commit date for a byte-for-byte reproducible archive. The exact command is +recorded in the package's own `README`. + +### Binary repacks — Debian `.deb` + +Packages such as `metasploit-framework-bin` are repacked from upstream `.deb` +archives (SBo convention: `.deb`/binary repacks take a `-bin` suffix): + +- Extract with: `ar p .deb data.tar.gz | tar xzv` +- Set `DOWNLOAD="UNSUPPORTED"` and use `DOWNLOAD_x86_64` / `MD5SUM_x86_64` + (plus the i386 pair when the package is multi-arch) +- Strip ELF binaries after extraction + +#### `metasploit-framework-bin`: msfvenom bash-completion + +The shipped `msfvenom.bash-completion` is a **pre-generated snapshot**, not a +static file. Upstream (kali) no longer ships it; they generate it at build +time with a ruby script that loads the framework and dumps the live +payload/encoder/arch/platform/format lists. We ship a snapshot instead of +running ruby at build time (hermetic build, no build-time dep). + +**Regenerate it on every version bump.** No host install needed: `test-build +--keep` produces a `.txz`; extract it to a scratchpad dir and run the +generator against the *extracted* framework's bundled ruby. This avoids `sudo +installpkg` and is fully in the agent's hands. + +**The `GEM_HOME`/`GEM_PATH`/`BUNDLE_GEMFILE` vars below are mandatory.** The +embedded ruby has `/opt/metasploit-framework` baked in as its prefix, so +bundler resolves gem paths there no matter where the tree was extracted, and +the run dies with: + +``` +Could not find metasploit-payloads-X, rex-socket-X, ... in locally installed +gems (Bundler::GemNotFound) +``` + +Pointing the gem vars at the extracted tree fixes it. Note `3.4.0` in that +path is the embedded **ruby version** and moves when upstream bumps ruby; +check `$FW/embedded/lib/ruby/gems/` if the path is wrong. + +```bash +KEPT=/data/sbo-test-build/kept/metasploit-framework-bin-$VERSION-x86_64-*.tgz +tar xf $KEPT -C $SCRATCH/msf-extract +FW=$SCRATCH/msf-extract/opt/metasploit-framework +curl -o $SCRATCH/gen.rb \ + https://gitlab.com/kalilinux/packages/metasploit-framework/-/raw/kali/master/debian/generate-msfvenom-bash-completion.rb +cd $FW/embedded/framework +GEM_HOME=$FW/embedded/lib/ruby/gems/3.4.0 \ +GEM_PATH=$FW/embedded/lib/ruby/gems/3.4.0 \ +BUNDLE_GEMFILE=$FW/embedded/framework/Gemfile \ +$FW/embedded/bin/ruby \ + -I$FW/embedded/framework/lib $SCRATCH/gen.rb \ + > network/metasploit-framework-bin/msfvenom.bash-completion +``` + +**Do not fall back to running the generator against a live +`/opt/metasploit-framework`.** Without the gem vars the extracted-tree run +only appears to work when a host install happens to sit at that path, and it +then reads the *installed* version, silently emitting completion data for +whatever is on the host rather than the version being packaged. That is how +the 2026-07-30 "byte-identical, no host install needed" claim was reached; it +was actually reading a host install. Corrected 2026-08-07 during the 6.5.1 +bump, where the host `/opt` still held 6.4.147. + +Verify the output is non-empty and the `%s` slots were filled (grep for real +payload names like `windows/meterpreter`), then commit it with the bump. + +#### `metasploit-framework-bin`: man pages + +The .deb ships **no** metasploit man pages (its `share/man` tree is only for +bundled deps like postgres/ruby). We ship `msfconsole.1` and `msfvenom.1` +from kali, who maintain them by hand (no generator script). The SlackBuild +gzips them into `/usr/man/man1`. **Refresh them on version bumps** in case +kali has updated them: + +```bash +for p in msfconsole msfvenom ; do + curl -o network/metasploit-framework-bin/$p.1 \ + https://gitlab.com/kalilinux/packages/metasploit-framework/-/raw/kali/master/debian/extra/$p.1 +done +``` + +For metasploit bumps, `PRGNAM=metasploit-framework-bin` with +`SRCNAM=metasploit-framework` drives the `.deb` glob and `/opt` path; pull +both-arch filenames and MD5s from the apt Packages indexes (`binary-amd64` +and `binary-i386`). + +### Data / archive packages + +Packages such as `SecLists`, `exploitdb` install data files rather than +compiled binaries. No stripping needed. + +--- + +## Test-building + +Because these packages are already published on SBo, the build here is a +**verification step** on a version bump, not development. It runs in a throwaway +Slackware container via the **`test-build`** tool, which lives in its own repo, +`../sbo-dockerbuild` (installed to `~/bin/test-build`). Being hermetic and +disposable, **the agent may run it directly** (unlike a real `slackrepo build` on +the buildsystem VM). + +Workflow for a bump: edit the `.SlackBuild`/`.info`, then verify on **both** +trees (these are all SBo-published packages, so both are mandatory): + +```bash +test-build # -current +test-build --stable # 15.0 +``` + +`test-build` resolves the target from the local dir (CWD or a path) and its deps +from the configured SBo tree, builds in a `--rm` container, and lints with +`sbopkglint`. Use `--keep` to copy the built `.txz` out (e.g. a binary repack +like `metasploit-framework-bin` whose post-install artifacts are regenerated by +extracting the kept `.txz` and running the generator against it, no host +install, but see the gem-path gotcha in the msfvenom bash-completion section +above). See `../sbo-dockerbuild` for the full tool and its image-builder +chain. + +The one artifact worth keeping from a clean bump is the **SBo submission +tarball** (`SBo/.tar.gz`), produced by the `post-commit` hook — that is +what gets uploaded to SlackBuilds.org. + +--- + +## SlackBuild Scripting Guidelines + +### Templates (local clone) + +A clone of the SBo templates lives at `~/Templates/SlackBuilds/sbo/` (refreshed +by `~/Templates/SlackBuilds/update-templates.sh`). **Start from the matching +file there** rather than from memory: + +- Per-build-type SlackBuilds: `autotools-`, `cmake-`, `meson-`, `python-`, + `perl-`, `rubygem-`, `haskell-template.SlackBuild`. +- Shared support files: `slack-desc`, `template.info`, `doinst.sh`, + `douninst.sh`. + +The [online SBo template](https://slackbuilds.org/templates/) remains the +authority; the local clone mirrors it. Refresh the clone if it looks stale +before relying on it. + +### General + +- Follow the SBo template (local clone above) as the base for all scripts +- Use `set -e` to abort on errors +- Honor `$TMP`, `$BUILD`, `$TAG`, `$OUTPUT` variables; default values must be set if unset +- Use `$ARCH` detection with proper `SLKCFLAGS` and `LIBDIRSUFFIX` +- Strip binaries and libraries unless upstream explicitly discourages it +- Install docs to `/usr/doc/$PRGNAM-$VERSION/` +- Always include `find -L` + `chown`/`chmod` cleanup block before packaging +- Copy repo files into `$PKG` with `cat src > dest`, never `cp`. `cat` writes + through a fresh destination so the build's umask/root ownership sets the + perms; `cp` bleeds the git working-tree mode/ownership into the package. + Applies to `slack-desc`, `doinst.sh`, and any file staged from `$CWD` + (SlackBuild, README, `.nvchecker`) into `$PKG`. +- Use `makepkg -l y -c n` to create the final package + +### `.info` file + +Must contain: +``` +PRGNAM, VERSION, HOMEPAGE, DOWNLOAD, MD5SUM (or SHA256SUM), REQUIRES, MAINTAINER, EMAIL +``` +- Checksums must match the exact source archive +- MAINTAINER/EMAIL are danix's, since this repo is his SBo-official packages +- Use `REQUIRES=""` if no SBo dependencies; list space-separated SBo package names otherwise + +### `slack-desc` + +- Exactly 11 lines in the `package-name: description` format +- First line: `package-name: package-name (short one-liner)` +- Lines 2–11: description, leave blank lines as `package-name:` +- Handy ruler line must be included (but not shipped) + +--- + +## Version Tracking: nvchecker + +A single `.extras/nvchecker.toml` tracks upstream versions for all packages. + +To check for new upstream versions: + +```bash +nvchecker -c .extras/nvchecker.toml +``` + +When a new version is detected, update `VERSION` in both `.SlackBuild` and +`.info`, then run `sbofixinfo` to refresh checksums. + +**Every package added to this repo must have a corresponding entry in +`.extras/nvchecker.toml`.** + +For **nvchecker** github stanzas prefer `use_latest_release` (hits +`releases/latest`, lenient) over `use_max_tag` (hits `git/refs/tags`, tightly +rate-limited and 403s under the shared anon budget); use `use_max_tag` only for +repos that tag but don't cut Releases (a `use_latest_release` probe 404s on +those). Probe ONE stanza with `nvchecker -c -e `. + +--- + +## Tooling: sbo-maintainer-tools + +Source: https://slackware.uk/~urchlay/repos/sbo-maintainer-tools + +| Tool | Purpose | +|------|---------| +| `sbolint` | Lint `.SlackBuild`, `README`, `.info`, `slack-desc` | +| `sbopkglint` | Lint the built package | +| `sbofixinfo` | Auto-fix common `.info` file issues | +| `sbodl` | Download sources and verify `MD5SUM`/`SHA256SUM` from `.info` | + +### Git hook setup + +Both hooks are tracked in `.extras/hooks/`. Install them after cloning: + +```bash +cp .extras/hooks/pre-commit .git/hooks/pre-commit +cp .extras/hooks/post-commit .git/hooks/post-commit +chmod +x .git/hooks/pre-commit .git/hooks/post-commit +``` + +To bypass the pre-commit lint check in exceptional cases: +```bash +SBOLINT=no git commit -m'Message here' +``` + +Note: `sbodl` creates symlinks in the package directory pointing to downloaded +sources. Remove them before staging; they must never be committed. Run it from +the repo root so no package is missed: + +```bash +find . -type l -print -delete +``` + +The `pre-commit` hook also strips staged symlinks to source archives and blocks +staged *real* archives, but do not rely on that as the only guard. + +### File modes: 0644 + +SBo requires 0644 for files and 0755 for directories, and the upload form +rejects otherwise. Git tracks the exec bit, so a `.SlackBuild` that was ever +`chmod +x` carries 0755 into the repo. `sbolint` catches it +(`must have mode 0644, not 0755`), which is one reason the pre-commit hook has +to actually run. To fix, both on disk and in the index: + +```bash +chmod 644 // +git add --chmod=-x // +``` + +Audit the whole repo (`.extras/hooks/` at 0755 is correct, those are hooks): + +```bash +git ls-files --stage | awk '$1!="100644" && $4 !~ /^\.extras/ {print $1, $4}' +``` + +--- + +## Who builds SlackBuilds + +The agent authors/edits the sources (`.SlackBuild`, `.info`, `README`, +`slack-desc`, `doinst.sh`, nvchecker stanzas) and runs the non-building checks +(`sbolint`, `sbodl`, `sbofixinfo`). + +**The one exception in this repo** is the throwaway-docker test-build via the +`test-build` tool (see [Test-building](#test-building)): it is hermetic and +disposable, so the agent may run it to verify a bump, including `sbopkglint` on +the throwaway package it produces. + +Everything else stays with the user: never run or offer a **real**, persistent +build — `slackrepo build`, or `bash .SlackBuild` / `sudo bash ...` on the +host (as opposed to inside the throwaway container). Those install to the +user's system or the buildsystem VM; the user runs them and reports back. + +--- + +## Delivery: getting a bump to SBo + +Two channels reach SlackBuilds.org. Everything up to the local commit is +identical for both; only the final step differs. + +### Channel 1: GitHub pull request (preferred for updates) + +Per SBo's own workflow doc (`https://slackbuilds.org/SBo-Github-Workflows.txt`). +Applies to **updates of already-published packages**, which is all this repo +holds. New submissions still go through the upload form, not a PR. + +The fork is a **separate clone**, not a remote of this repo, the two trees +have unrelated histories: + +``` +~/Programming/GIT/GITHUB/slackbuilds # fork of SlackBuildsOrg/slackbuilds + origin -> github:danixland/slackbuilds.git + upstream -> https://github.com/SlackBuildsOrg/slackbuilds.git + user.name = danix (local override, matches .info MAINTAINER) +``` + +To recreate it (the clone is ~265MB, and `.git/config` is not tracked, so a +fresh clone silently loses the name override and commits revert to the global +`Danilo M.`): + +```bash +gh repo fork SlackBuildsOrg/slackbuilds --clone=false +git clone github:danixland/slackbuilds.git ~/Programming/GIT/GITHUB/slackbuilds +cd ~/Programming/GIT/GITHUB/slackbuilds +git remote add upstream https://github.com/SlackBuildsOrg/slackbuilds.git +git config --local user.name danix # email + GPG signing come from global +``` + +Identity must satisfy three things, all verifiable on a pushed commit with +`gh api repos/SlackBuildsOrg/slackbuilds/pulls//commits`: the author email +matches `.info` EMAIL, the email is verified on the `danixland` account (so +`.author.login` is set, not null), and the GPG key is uploaded there (so +`.commit.verification.verified` is true). All three held as of 2026-08-08. + +Because this repo mirrors SBo's `//` layout, a package +directory copies across at the identical relative path, no mapping needed: + +```bash +cd ~/Programming/GIT/GITHUB/slackbuilds +git fetch upstream +git checkout -B upstream/master +rsync -a --delete ~/Programming/GIT/sbo-slackbuilds/// // +git add / +git commit -m "/: Updated for version ." +git push -f origin +gh pr create --repo SlackBuildsOrg/slackbuilds --base master +``` + +Notes: + +- **One PR per package**, one commit per PR. Local history here can be as + fine-grained as you like; the PR commit is synthesized at export time, so + the two histories deliberately diverge. +- **Commit subject uses SBo's wording**, not this repo's: + `/: Updated for version X.Y.Z.` (past tense, trailing + period). Repo-level commits here (AGENTS.md, hooks) keep no prefix and are + never exported. +- **Base the PR on `master`.** Merged PRs display a base of `github`, a + transient integration branch SBo admins retarget onto and then delete. Open + PRs target `master`; that is what you branch from and PR against. +- Reviewer feedback is addressed by amending and force-pushing the single + commit, per the doc. Local history here needn't mirror that amendment. + +### Channel 2: submission tarball (fallback) + +The `post-commit` hook builds `SBo/.tar.gz` when a `.SlackBuild` +changes and `SBO_ARCHIVE=yes` is set. The archive is named after the package +with the **package** directory at its root (not the category), as the upload +form expects. `SBo/` is gitignored, the tarball is a local artifact. + +Use this when a PR would be slower than the form, or as a fallback if a PR +stalls. + +--- + +## SBo Submission Guidelines + +Before submitting or updating a package on SlackBuilds.org: + +1. **Pass all lint checks** — `sbolint` and `sbopkglint` must report no errors +2. **Test the build** on a clean Slackware installation (or VM snapshot) +3. **Verify checksums** via `sbodl` before committing +4. **Check `README`** includes all non-SBo dependencies and any special build notes +5. **Follow the SBo submission guidelines**: https://slackbuilds.org/guidelines/ +6. **Bump `VERSION`** in both `.SlackBuild` and `.info` when updating +7. **Run `sbofixinfo`** after every version bump to catch stale checksums/URLs + +--- + +## Commit Conventions + +Local commits in this repo: + +- One commit per package add/update +- Commit message format: `: add version X.Y.Z` or `: update to X.Y.Z` +- For fixes: `: fix ` +- Repo-level changes (AGENTS.md, hooks, nvchecker config) take no package + prefix and are never exported + +The **exported PR commit uses SBo's wording instead**, generated from the path +and `.info` VERSION at export time: `/: Updated for version +X.Y.Z.` See [Delivery](#delivery-getting-a-bump-to-sbo). The two histories are +independent by design, so local commits need not adopt SBo's format. + +--- + +## Maintainer + +danix diff --git a/CLAUDE.md b/CLAUDE.md index 7316637..e4e842f 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,489 +1 @@ -# SBo SlackBuilds Repository - -SlackBuild scripts for which danix is the **official SBo maintainer** on -[SlackBuilds.org (SBo)](https://slackbuilds.org). - -## Purpose: tracking, not development - -This repo is a **maintenance mirror of already-published SBo packages**. No new -packages are developed here. Its job is the ongoing upkeep of packages already -on SBo: - -1. Track upstream version changes (via nvchecker). -2. Reflect a new upstream version in the package's `.SlackBuild` / `.info`. -3. Test-build with the `test-build` tool (see below). -4. Generate the SBo submission tarball to upload. - -New-package development happens in **other** repos, not here: - -- `../GITHUB/my-slackbuilds/` — regular packages, plus SBo packages whose - upstream moves faster than SBo review (worked ahead of the SBo copy). -- `../GITHUB/Slackware-Pentesting-Suite/` — cybersecurity packages. - -When a new package is uploaded to SBo and approved, it **moves here** and this -repo takes over its maintenance. - ---- - -## Repo Structure - -Packages live under their SBo category, mirroring the layout of the SBo repo -itself (`//`): - -``` -// -├── .SlackBuild # Main build script -├── .info # Metadata (version, checksums, URLs) -├── README # Description and usage notes -├── slack-desc # Package description (11-line format) -├── .desktop # (optional) Desktop entry for GUI apps -└── [...] # other optional files -``` - -The category is not recorded anywhere else: the directory *is* the category. -It is authoritative in the synced SBo tree, so to find where a package -belongs: - -```bash -find /var/lib/sbopkg/SBo-stable -maxdepth 2 -mindepth 2 -type d -name '' -``` - -Current categories: `misc` (SecLists, exploitdb, nuclei), `games` -(UrbanTerror), `network` (feroxbuster, ffuf, gobuster, -metasploit-framework-bin, r8125). - -Matching SBo's layout means a package directory exports to the SBo repo at -the identical relative path, with no mapping step. Both git hooks locate a -build by walking up to the directory holding the `.SlackBuild`, so neither -asserts a fixed depth. - -Version tracking is handled by a single file: - -``` -.extras/nvchecker.toml # nvchecker config listing all packages -``` - -### `.extras/` holds all non-package repo files - -Anything that is not a SlackBuild package must live under `.extras/`, never at -the repo root. Currently: `nvchecker.toml` (version tracking), `hooks/` (git -hooks), `assets/`. - ---- - -## Build Strategies - -Packages fall into several categories; the SlackBuild style differs -accordingly. - -### Source builds (Go) - -Packages such as `ffuf`, `gobuster`, `nuclei` are built from upstream source -tarballs using `go build`. Key points: - -- Set `GOPATH`, `GOPROXY`, `GOFLAGS` before building -- Use `-buildmode=pie -trimpath -mod=readonly -modcacherw` -- Strip ELF binaries after build -- Clean up `$GOPATH` / Go module cache before packaging -- `REQUIRES="google-go-lang"` in the `.info` file - -### Source builds (Rust) - -Packages such as `feroxbuster` build from a vendored crates tarball -(`--vendor.tar.gz`) declared as a second source in `.info`, -alongside the upstream tarball. The SlackBuild unpacks it, points cargo at it -via `.cargo/config.toml`, and builds fully offline (`cargo build --offline ---locked`). The vendor tarball is generated once per version with -`cargo-vendor-filterer`, with `SOURCE_DATE_EPOCH` pinned to the release tag's -commit date for a byte-for-byte reproducible archive. The exact command is -recorded in the package's own `README`. - -### Binary repacks — Debian `.deb` - -Packages such as `metasploit-framework-bin` are repacked from upstream `.deb` -archives (SBo convention: `.deb`/binary repacks take a `-bin` suffix): - -- Extract with: `ar p .deb data.tar.gz | tar xzv` -- Set `DOWNLOAD="UNSUPPORTED"` and use `DOWNLOAD_x86_64` / `MD5SUM_x86_64` - (plus the i386 pair when the package is multi-arch) -- Strip ELF binaries after extraction - -#### `metasploit-framework-bin`: msfvenom bash-completion - -The shipped `msfvenom.bash-completion` is a **pre-generated snapshot**, not a -static file. Upstream (kali) no longer ships it; they generate it at build -time with a ruby script that loads the framework and dumps the live -payload/encoder/arch/platform/format lists. We ship a snapshot instead of -running ruby at build time (hermetic build, no build-time dep). - -**Regenerate it on every version bump.** No host install needed: `test-build ---keep` produces a `.txz`; extract it to a scratchpad dir and run the -generator against the *extracted* framework's bundled ruby. This avoids `sudo -installpkg` and is fully in Claude's hands. - -**The `GEM_HOME`/`GEM_PATH`/`BUNDLE_GEMFILE` vars below are mandatory.** The -embedded ruby has `/opt/metasploit-framework` baked in as its prefix, so -bundler resolves gem paths there no matter where the tree was extracted, and -the run dies with: - -``` -Could not find metasploit-payloads-X, rex-socket-X, ... in locally installed -gems (Bundler::GemNotFound) -``` - -Pointing the gem vars at the extracted tree fixes it. Note `3.4.0` in that -path is the embedded **ruby version** and moves when upstream bumps ruby; -check `$FW/embedded/lib/ruby/gems/` if the path is wrong. - -```bash -KEPT=/data/sbo-test-build/kept/metasploit-framework-bin-$VERSION-x86_64-*.tgz -tar xf $KEPT -C $SCRATCH/msf-extract -FW=$SCRATCH/msf-extract/opt/metasploit-framework -curl -o $SCRATCH/gen.rb \ - https://gitlab.com/kalilinux/packages/metasploit-framework/-/raw/kali/master/debian/generate-msfvenom-bash-completion.rb -cd $FW/embedded/framework -GEM_HOME=$FW/embedded/lib/ruby/gems/3.4.0 \ -GEM_PATH=$FW/embedded/lib/ruby/gems/3.4.0 \ -BUNDLE_GEMFILE=$FW/embedded/framework/Gemfile \ -$FW/embedded/bin/ruby \ - -I$FW/embedded/framework/lib $SCRATCH/gen.rb \ - > network/metasploit-framework-bin/msfvenom.bash-completion -``` - -**Do not fall back to running the generator against a live -`/opt/metasploit-framework`.** Without the gem vars the extracted-tree run -only appears to work when a host install happens to sit at that path, and it -then reads the *installed* version, silently emitting completion data for -whatever is on the host rather than the version being packaged. That is how -the 2026-07-30 "byte-identical, no host install needed" claim was reached; it -was actually reading a host install. Corrected 2026-08-07 during the 6.5.1 -bump, where the host `/opt` still held 6.4.147. - -Verify the output is non-empty and the `%s` slots were filled (grep for real -payload names like `windows/meterpreter`), then commit it with the bump. - -#### `metasploit-framework-bin`: man pages - -The .deb ships **no** metasploit man pages (its `share/man` tree is only for -bundled deps like postgres/ruby). We ship `msfconsole.1` and `msfvenom.1` -from kali, who maintain them by hand (no generator script). The SlackBuild -gzips them into `/usr/man/man1`. **Refresh them on version bumps** in case -kali has updated them: - -```bash -for p in msfconsole msfvenom ; do - curl -o network/metasploit-framework-bin/$p.1 \ - https://gitlab.com/kalilinux/packages/metasploit-framework/-/raw/kali/master/debian/extra/$p.1 -done -``` - -For metasploit bumps, `PRGNAM=metasploit-framework-bin` with -`SRCNAM=metasploit-framework` drives the `.deb` glob and `/opt` path; pull -both-arch filenames and MD5s from the apt Packages indexes (`binary-amd64` -and `binary-i386`). - -### Data / archive packages - -Packages such as `SecLists`, `exploitdb` install data files rather than -compiled binaries. No stripping needed. - ---- - -## Test-building - -Because these packages are already published on SBo, the build here is a -**verification step** on a version bump, not development. It runs in a throwaway -Slackware container via the **`test-build`** tool, which lives in its own repo, -`../sbo-dockerbuild` (installed to `~/bin/test-build`). Being hermetic and -disposable, **Claude may run it directly** (unlike a real `slackrepo build` on -the buildsystem VM). - -Workflow for a bump: edit the `.SlackBuild`/`.info`, then verify on **both** -trees (these are all SBo-published packages, so both are mandatory): - -```bash -test-build # -current -test-build --stable # 15.0 -``` - -`test-build` resolves the target from the local dir (CWD or a path) and its deps -from the configured SBo tree, builds in a `--rm` container, and lints with -`sbopkglint`. Use `--keep` to copy the built `.txz` out (e.g. a binary repack -like `metasploit-framework-bin` whose post-install artifacts are regenerated by -extracting the kept `.txz` and running the generator against it, no host -install, but see the gem-path gotcha in the msfvenom bash-completion section -above). See `../sbo-dockerbuild` for the full tool and its image-builder -chain. - -The one artifact worth keeping from a clean bump is the **SBo submission -tarball** (`SBo/.tar.gz`), produced by the `post-commit` hook — that is -what gets uploaded to SlackBuilds.org. - ---- - -## SlackBuild Scripting Guidelines - -### Templates (local clone) - -A clone of the SBo templates lives at `~/Templates/SlackBuilds/sbo/` (refreshed -by `~/Templates/SlackBuilds/update-templates.sh`). **Start from the matching -file there** rather than from memory: - -- Per-build-type SlackBuilds: `autotools-`, `cmake-`, `meson-`, `python-`, - `perl-`, `rubygem-`, `haskell-template.SlackBuild`. -- Shared support files: `slack-desc`, `template.info`, `doinst.sh`, - `douninst.sh`. - -The [online SBo template](https://slackbuilds.org/templates/) remains the -authority; the local clone mirrors it. Refresh the clone if it looks stale -before relying on it. - -### General - -- Follow the SBo template (local clone above) as the base for all scripts -- Use `set -e` to abort on errors -- Honor `$TMP`, `$BUILD`, `$TAG`, `$OUTPUT` variables; default values must be set if unset -- Use `$ARCH` detection with proper `SLKCFLAGS` and `LIBDIRSUFFIX` -- Strip binaries and libraries unless upstream explicitly discourages it -- Install docs to `/usr/doc/$PRGNAM-$VERSION/` -- Always include `find -L` + `chown`/`chmod` cleanup block before packaging -- Copy repo files into `$PKG` with `cat src > dest`, never `cp`. `cat` writes - through a fresh destination so the build's umask/root ownership sets the - perms; `cp` bleeds the git working-tree mode/ownership into the package. - Applies to `slack-desc`, `doinst.sh`, and any file staged from `$CWD` - (SlackBuild, README, `.nvchecker`) into `$PKG`. -- Use `makepkg -l y -c n` to create the final package - -### `.info` file - -Must contain: -``` -PRGNAM, VERSION, HOMEPAGE, DOWNLOAD, MD5SUM (or SHA256SUM), REQUIRES, MAINTAINER, EMAIL -``` -- Checksums must match the exact source archive -- MAINTAINER/EMAIL are danix's, since this repo is his SBo-official packages -- Use `REQUIRES=""` if no SBo dependencies; list space-separated SBo package names otherwise - -### `slack-desc` - -- Exactly 11 lines in the `package-name: description` format -- First line: `package-name: package-name (short one-liner)` -- Lines 2–11: description, leave blank lines as `package-name:` -- Handy ruler line must be included (but not shipped) - ---- - -## Version Tracking: nvchecker - -A single `.extras/nvchecker.toml` tracks upstream versions for all packages. - -To check for new upstream versions: - -```bash -nvchecker -c .extras/nvchecker.toml -``` - -When a new version is detected, update `VERSION` in both `.SlackBuild` and -`.info`, then run `sbofixinfo` to refresh checksums. - -**Every package added to this repo must have a corresponding entry in -`.extras/nvchecker.toml`.** - -For **nvchecker** github stanzas prefer `use_latest_release` (hits -`releases/latest`, lenient) over `use_max_tag` (hits `git/refs/tags`, tightly -rate-limited and 403s under the shared anon budget); use `use_max_tag` only for -repos that tag but don't cut Releases (a `use_latest_release` probe 404s on -those). Probe ONE stanza with `nvchecker -c -e `. - ---- - -## Tooling: sbo-maintainer-tools - -Source: https://slackware.uk/~urchlay/repos/sbo-maintainer-tools - -| Tool | Purpose | -|------|---------| -| `sbolint` | Lint `.SlackBuild`, `README`, `.info`, `slack-desc` | -| `sbopkglint` | Lint the built package | -| `sbofixinfo` | Auto-fix common `.info` file issues | -| `sbodl` | Download sources and verify `MD5SUM`/`SHA256SUM` from `.info` | - -### Git hook setup - -Both hooks are tracked in `.extras/hooks/`. Install them after cloning: - -```bash -cp .extras/hooks/pre-commit .git/hooks/pre-commit -cp .extras/hooks/post-commit .git/hooks/post-commit -chmod +x .git/hooks/pre-commit .git/hooks/post-commit -``` - -To bypass the pre-commit lint check in exceptional cases: -```bash -SBOLINT=no git commit -m'Message here' -``` - -Note: `sbodl` creates symlinks in the package directory pointing to downloaded -sources. Remove them before staging; they must never be committed. Run it from -the repo root so no package is missed: - -```bash -find . -type l -print -delete -``` - -The `pre-commit` hook also strips staged symlinks to source archives and blocks -staged *real* archives, but do not rely on that as the only guard. - -### File modes: 0644 - -SBo requires 0644 for files and 0755 for directories, and the upload form -rejects otherwise. Git tracks the exec bit, so a `.SlackBuild` that was ever -`chmod +x` carries 0755 into the repo. `sbolint` catches it -(`must have mode 0644, not 0755`), which is one reason the pre-commit hook has -to actually run. To fix, both on disk and in the index: - -```bash -chmod 644 // -git add --chmod=-x // -``` - -Audit the whole repo (`.extras/hooks/` at 0755 is correct, those are hooks): - -```bash -git ls-files --stage | awk '$1!="100644" && $4 !~ /^\.extras/ {print $1, $4}' -``` - ---- - -## Who builds SlackBuilds - -Claude authors/edits the sources (`.SlackBuild`, `.info`, `README`, -`slack-desc`, `doinst.sh`, nvchecker stanzas) and runs the non-building checks -(`sbolint`, `sbodl`, `sbofixinfo`). - -**The one exception in this repo** is the throwaway-docker test-build via the -`test-build` tool (see [Test-building](#test-building)): it is hermetic and -disposable, so Claude may run it to verify a bump, including `sbopkglint` on -the throwaway package it produces. - -Everything else stays with the user: never run or offer a **real**, persistent -build — `slackrepo build`, or `bash .SlackBuild` / `sudo bash ...` on the -host (as opposed to inside the throwaway container). Those install to the -user's system or the buildsystem VM; the user runs them and reports back. - ---- - -## Delivery: getting a bump to SBo - -Two channels reach SlackBuilds.org. Everything up to the local commit is -identical for both; only the final step differs. - -### Channel 1: GitHub pull request (preferred for updates) - -Per SBo's own workflow doc (`https://slackbuilds.org/SBo-Github-Workflows.txt`). -Applies to **updates of already-published packages**, which is all this repo -holds. New submissions still go through the upload form, not a PR. - -The fork is a **separate clone**, not a remote of this repo, the two trees -have unrelated histories: - -``` -~/Programming/GIT/GITHUB/slackbuilds # fork of SlackBuildsOrg/slackbuilds - origin -> github:danixland/slackbuilds.git - upstream -> https://github.com/SlackBuildsOrg/slackbuilds.git - user.name = danix (local override, matches .info MAINTAINER) -``` - -To recreate it (the clone is ~265MB, and `.git/config` is not tracked, so a -fresh clone silently loses the name override and commits revert to the global -`Danilo M.`): - -```bash -gh repo fork SlackBuildsOrg/slackbuilds --clone=false -git clone github:danixland/slackbuilds.git ~/Programming/GIT/GITHUB/slackbuilds -cd ~/Programming/GIT/GITHUB/slackbuilds -git remote add upstream https://github.com/SlackBuildsOrg/slackbuilds.git -git config --local user.name danix # email + GPG signing come from global -``` - -Identity must satisfy three things, all verifiable on a pushed commit with -`gh api repos/SlackBuildsOrg/slackbuilds/pulls//commits`: the author email -matches `.info` EMAIL, the email is verified on the `danixland` account (so -`.author.login` is set, not null), and the GPG key is uploaded there (so -`.commit.verification.verified` is true). All three held as of 2026-08-08. - -Because this repo mirrors SBo's `//` layout, a package -directory copies across at the identical relative path, no mapping needed: - -```bash -cd ~/Programming/GIT/GITHUB/slackbuilds -git fetch upstream -git checkout -B upstream/master -rsync -a --delete ~/Programming/GIT/sbo-slackbuilds/// // -git add / -git commit -m "/: Updated for version ." -git push -f origin -gh pr create --repo SlackBuildsOrg/slackbuilds --base master -``` - -Notes: - -- **One PR per package**, one commit per PR. Local history here can be as - fine-grained as you like; the PR commit is synthesized at export time, so - the two histories deliberately diverge. -- **Commit subject uses SBo's wording**, not this repo's: - `/: Updated for version X.Y.Z.` (past tense, trailing - period). Repo-level commits here (CLAUDE.md, hooks) keep no prefix and are - never exported. -- **Base the PR on `master`.** Merged PRs display a base of `github`, a - transient integration branch SBo admins retarget onto and then delete. Open - PRs target `master`; that is what you branch from and PR against. -- Reviewer feedback is addressed by amending and force-pushing the single - commit, per the doc. Local history here needn't mirror that amendment. - -### Channel 2: submission tarball (fallback) - -The `post-commit` hook builds `SBo/.tar.gz` when a `.SlackBuild` -changes and `SBO_ARCHIVE=yes` is set. The archive is named after the package -with the **package** directory at its root (not the category), as the upload -form expects. `SBo/` is gitignored, the tarball is a local artifact. - -Use this when a PR would be slower than the form, or as a fallback if a PR -stalls. - ---- - -## SBo Submission Guidelines - -Before submitting or updating a package on SlackBuilds.org: - -1. **Pass all lint checks** — `sbolint` and `sbopkglint` must report no errors -2. **Test the build** on a clean Slackware installation (or VM snapshot) -3. **Verify checksums** via `sbodl` before committing -4. **Check `README`** includes all non-SBo dependencies and any special build notes -5. **Follow the SBo submission guidelines**: https://slackbuilds.org/guidelines/ -6. **Bump `VERSION`** in both `.SlackBuild` and `.info` when updating -7. **Run `sbofixinfo`** after every version bump to catch stale checksums/URLs - ---- - -## Commit Conventions - -Local commits in this repo: - -- One commit per package add/update -- Commit message format: `: add version X.Y.Z` or `: update to X.Y.Z` -- For fixes: `: fix ` -- Repo-level changes (CLAUDE.md, hooks, nvchecker config) take no package - prefix and are never exported - -The **exported PR commit uses SBo's wording instead**, generated from the path -and `.info` VERSION at export time: `/: Updated for version -X.Y.Z.` See [Delivery](#delivery-getting-a-bump-to-sbo). The two histories are -independent by design, so local commits need not adopt SBo's format. - ---- - -## Maintainer - -danix +See AGENTS.md for all repository instructions. diff --git a/TODO.md b/TODO.md index af04a93..f0f2684 100644 --- a/TODO.md +++ b/TODO.md @@ -3,7 +3,7 @@ ## Staging convention: prefer `cat` over `cp` Packages moved here from the pentesting-suite repo predate this repo's -convention (see `CLAUDE.md`) of staging repo files into `$PKG` with +convention (see `AGENTS.md`) of staging repo files into `$PKG` with `cat src > dest` instead of `cp`. `cat` writes through a fresh destination so the build's umask/root ownership sets the perms; `cp` bleeds the git working-tree mode/ownership into the package. -- cgit v1.2.3