diff options
| -rw-r--r-- | AGENTS.md | 280 | ||||
| -rw-r--r-- | CLAUDE.md | 201 | ||||
| -rw-r--r-- | README.md | 4 |
3 files changed, 482 insertions, 3 deletions
diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..4623c18 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,280 @@ +# Agent Instructions — Slackware Pentesting Suite + +This file governs how AI agents must behave in this repository. +**Read it in full before taking any action.** + +--- + +## Core Rules + +1. **Ask before acting.** If anything about the task is ambiguous — target + version, which package, which build strategy — stop and ask. Do not infer + intent and proceed. +2. **Use available skills.** For git operations, commits, PRs, and any task + covered by a skill, invoke the relevant skill. Do not improvise a workflow + that a skill already defines. +3. **One package per task.** Never modify multiple packages in a single + operation unless explicitly instructed. +4. **Never skip lint.** Every change must pass `sbolint` before committing. + No exceptions. +5. **Never commit without being asked.** Complete all file edits and + verification steps, then wait for explicit instruction to commit. + +--- + +## Repository Layout + +Each package lives in its own top-level subfolder: + +``` +<package-name>/ +├── <package-name>.SlackBuild # Main build script +├── <package-name>.info # Metadata (version, checksums, download URL) +├── README # Description and usage notes +├── slack-desc # 11-line package description +├── <package-name>.desktop # (optional) Desktop entry for GUI apps +├── doinst.sh # (optional) Post-install script +├── rc.<daemon> # (optional) Init script for daemon packages +├── patches/ # (optional) Patch directory +│ ├── series # (optional) Ordered patch list +│ └── *.patch +└── [...] # Other optional files +``` + +--- + +## Package Build Strategies + +Before updating or adding a package, identify which build strategy it uses: + +| Strategy | Examples | Key indicator | +|----------|----------|---------------| +| Go source | ffuf, gobuster, nuclei | `go build`, `REQUIRES="google-go-lang"` | +| Autotools/cmake source | hydra, cadaver | `./configure` or `cmake` | +| Binary repack (.deb) | metasploit-framework | `ar p … data.tar.gz \| tar xzv` | +| Binary repack (.rpm) | nessus | `rpm2cpio … \| cpio -idmv` | +| Data archive | SecLists, exploitdb, webshells, windows-binaries | no compilation | + +The update workflow below applies to all strategies. Differences are called +out at each step. + +--- + +## Mandatory Workflow: Updating a Package Version + +Follow these steps in order. Do not skip or reorder them. + +### Step 1 — Identify the build strategy + +Read `<package-name>/<package-name>.SlackBuild` to determine which strategy +the package uses (see table above). This affects how the download URL and +checksum are handled. + +### Step 2 — Update version strings + +Edit **both** of the following files, changing the old version to the new one: + +- `<package-name>/<package-name>.SlackBuild` — change `VERSION=${VERSION:-<old>}` to the new value +- `<package-name>/<package-name>.info` — change `VERSION=`, `DOWNLOAD=` + (or `DOWNLOAD_x86_64=`), and the corresponding `MD5SUM=` / `MD5SUM_x86_64=` + +For the download URL, substitute the new version into the existing URL pattern. +Set the checksum field to `"placeholder"` — it will be fixed in the next step. + +**Binary repack packages:** the download URL typically contains a timestamp or +build ID embedded by upstream (e.g. Rapid7's `.deb` filenames). Confirm the +exact URL for the new version before editing. + +### Step 3 — Fix the checksum + +Run `sbofixinfo` from inside the package directory: + +```bash +cd <package-name> && sbofixinfo +``` + +If `sbofixinfo` reports no changes (common when the checksum is a placeholder), +use the two-pass `sbodl` procedure instead: + +```bash +# Pass 1 — downloads the source; fails because MD5SUM is wrong/placeholder +cd <package-name> && sbodl + +# Compute the real checksum from the downloaded file +md5sum <downloaded-file> # adjust filename as needed + +# Update the MD5SUM (or MD5SUM_x86_64) in the .info file + +# Pass 2 — verifies the checksum; must report "md5sum matches OK" +cd <package-name> && sbodl +``` + +Do not proceed past this step until `sbodl` reports `md5sum matches OK`. + +**Binary repack packages:** if `sbodl` cannot download the file automatically +(e.g. Nessus requires a browser session), download it manually, place it in +the package directory, compute `md5sum <file>`, update the `.info` file, then +run `sbodl` for the verification pass. + +### Step 4 — Lint + +```bash +cd <package-name> && sbolint +``` + +`sbolint` must report no errors. Fix any issues before continuing. + +### Step 5 — Report and wait + +Present a summary of all changes made and wait for the user to instruct you +to commit. + +--- + +## Mandatory Workflow: Adding a New Package + +Before creating any files, ask the user for: + +- The exact `PRGNAM` (package name) +- The upstream source URL and version +- The build strategy (source / binary repack / data archive) +- Any non-SBo runtime dependencies + +Then proceed: + +1. Create the package directory with all required files: + `<prgnam>.SlackBuild`, `<prgnam>.info`, `README`, `slack-desc` +2. Choose the correct build strategy and follow the scripting rules below. +3. Run `sbofixinfo`, then `sbodl` (two-pass if needed), then `sbolint`. +4. Report results and wait for commit instruction. + +--- + +## SlackBuild Scripting Rules + +- Base all scripts on the SBo template: https://slackbuilds.org/templates/ +- Use `set -e` (abort on error). +- Honor `$TMP`, `$BUILD`, `$TAG`, `$OUTPUT`; provide defaults if unset. +- Detect `$ARCH` and set `SLKCFLAGS` and `LIBDIRSUFFIX` accordingly. +- Strip ELF binaries and shared objects (skip for pure data packages). +- Install docs to `/usr/doc/$PRGNAM-$VERSION/`. +- Always include the `find -L` + `chown`/`chmod` cleanup block before packaging. +- Build the package with `makepkg -l y -c n`. + +### Go source builds + +```bash +export CGO_CPPFLAGS="$SLKCFLAGS" +export CGO_CFLAGS="$SLKCFLAGS" +export CGO_CXXFLAGS="$SLKCFLAGS" +export GOPATH="$(pwd)/.gocache" +export GOPROXY="https://proxy.golang.org,direct" +export GOFLAGS="-mod=readonly -buildmode=pie -trimpath -modcacherw" +LIB_LDFLAGS="-linkmode=external -s -w" + +go build -ldflags="$LIB_LDFLAGS" -o "$PKG"/usr/bin/ ./... + +# Clean up the Go module cache before packaging +rm -rf "$GOPATH" +``` + +### Binary repack from `.deb` + +```bash +# x86_64 only — exit with error for other arches +if [ "$ARCH" != "x86_64" ]; then + echo "Sorry, $PRGNAM binaries are available for x86_64 only." + exit 1 +fi + +ar p $CWD/${PRGNAM}_${VERSION}*.deb data.tar.gz | tar xzv +``` + +Use `DOWNLOAD="UNSUPPORTED"` and `DOWNLOAD_x86_64="<url>"` in the `.info` file. + +### Binary repack from `.rpm` + +```bash +rpm2cpio $CWD/${PRGNAM}-${VERSION}*.rpm | cpio -idmv +``` + +Use `DOWNLOAD="UNSUPPORTED"` and `DOWNLOAD_x86_64="<url>"` in the `.info` file. + +### Patch support + +When patches are needed, store them in `patches/` and apply with: + +```bash +if compgen -G "$CWD/patches/*.patch" > /dev/null; then + if [ -f "$CWD/patches/series" ]; then + while IFS= read -r PATCH; do + [ -z "$PATCH" ] && continue + [ "${PATCH#\#}" != "$PATCH" ] && continue + patch -p1 -i "$CWD/patches/$PATCH" + done < "$CWD/patches/series" + else + for PATCH in "$CWD"/patches/*.patch; do + patch -p1 -i "$PATCH" + done + fi +fi +``` + +### `.info` file — required fields + +``` +PRGNAM="..." +VERSION="..." +HOMEPAGE="..." +DOWNLOAD="..." +MD5SUM="..." +DOWNLOAD_x86_64="" +MD5SUM_x86_64="" +REQUIRES="" +MAINTAINER="danix" +EMAIL="danix@danix.xyz" +``` + +- Use `DOWNLOAD="UNSUPPORTED"` when no 32-bit download exists. +- For packages originally authored by others (e.g. Nessus), preserve the + original `MAINTAINER` and `EMAIL` — do not overwrite with danix's details. + +### `slack-desc` rules + +- Exactly 11 lines, each prefixed with `package-name: `. +- Line 1: `package-name: package-name (short one-liner description)` +- Lines 2–11: prose description; blank lines use `package-name:` only. +- Do not include the ruler line in the committed file. + +--- + +## Git Operations + +**Use the commit skill for all commits.** Do not run `git commit` manually. + +**Remove symlinks before staging.** `sbodl` creates symlinks in the package +directory pointing to downloaded source archives. These must never be committed +to git. Before any `git add`, run from the repo root: + +```bash +find . -type l -delete +``` + +Commit conventions: +- One commit per package add or update. +- Message format: + - Add: `<package-name>: add version X.Y.Z` + - Update: `<package-name>: update to X.Y.Z` + - Fix: `<package-name>: fix <short description>` + +--- + +## What Requires User Confirmation + +Stop and ask before doing any of the following: + +- Committing or pushing changes +- Modifying files in more than one package directory +- Deleting any file +- Bypassing the pre-commit hook (`SBOLINT=no`) +- Any action not covered by the workflows above diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..8e29936 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,201 @@ +# Slackware Pentesting Suite + +A curated collection of penetration testing tools packaged as SlackBuilds for +Slackware GNU/Linux, following [SlackBuilds.org (SBo)](https://slackbuilds.org) +conventions where applicable. + +--- + +## Repo Structure + +Each package lives in its own top-level subfolder: + +``` +<package-name>/ +├── <package-name>.SlackBuild # Main build script +├── <package-name>.info # Metadata (version, checksums, URLs) +├── README # Description and usage notes +├── slack-desc # Package description (11-line format) +├── <package-name>.desktop # (optional) Desktop entry for GUI apps +├── doinst.sh # (optional) Post-install script +├── rc.<daemon> # (optional) Init script for daemon packages +├── patches/ # (optional) Patch directory for source builds +│ ├── series # (optional) Ordered patch list +│ └── *.patch +└── [...] # Other optional files (man pages, completions, etc.) +``` + +--- + +## Build Strategies + +Packages in this repo fall into several categories — the SlackBuild style +differs accordingly. + +### 1. 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 + +### 2. Source builds (autotools / cmake) + +Packages such as `hydra`, `cadaver` are built from source using `./configure` +or `cmake`. Follow standard SBo template conventions. + +### 3. Binary repacks — Debian `.deb` + +Packages such as `metasploit-framework` are repacked from upstream `.deb` +archives: + +- Extract with: `ar p <file>.deb data.tar.gz | tar xzv` +- Set `DOWNLOAD="UNSUPPORTED"` and use `DOWNLOAD_x86_64` / `MD5SUM_x86_64` +- These packages are x86_64 only; exit with an error for other arches +- Strip ELF binaries after extraction + +### 4. Binary repacks — RPM + +Packages such as `nessus` are repacked from upstream `.rpm` archives: + +- Extract with: `rpm2cpio <file>.rpm | cpio -idmv` +- Set `DOWNLOAD="UNSUPPORTED"` and use `DOWNLOAD_x86_64` / `MD5SUM_x86_64` + +### 5. Data / archive packages + +Packages such as `SecLists`, `exploitdb`, `webshells`, `windows-binaries` +install data files rather than compiled binaries. No stripping needed. + +--- + +## SlackBuild Scripting Guidelines + +- Follow the [SBo template](https://slackbuilds.org/templates/) as the base +- Use `set -e` to abort on errors +- Honor `$TMP`, `$BUILD`, `$TAG`, `$OUTPUT`; provide defaults if unset +- Use `$ARCH` detection with proper `SLKCFLAGS` and `LIBDIRSUFFIX` +- Strip binaries and libraries unless the package type makes it irrelevant +- Install docs to `/usr/doc/$PRGNAM-$VERSION/` +- Always include `find -L` + `chown`/`chmod` cleanup block before packaging +- Use `makepkg -l y -c n` to create the final package + +### Patch support + +When upstream patches are needed, store them in `patches/` and apply via: + +```bash +if compgen -G "$CWD/patches/*.patch" > /dev/null; then + if [ -f "$CWD/patches/series" ]; then + while IFS= read -r PATCH; do + [ -z "$PATCH" ] && continue + [ "${PATCH#\#}" != "$PATCH" ] && continue + patch -p1 -i "$CWD/patches/$PATCH" + done < "$CWD/patches/series" + else + for PATCH in "$CWD"/patches/*.patch; do + patch -p1 -i "$PATCH" + done + fi +fi +``` + +--- + +## `.info` File + +Must contain: + +``` +PRGNAM="..." +VERSION="..." +HOMEPAGE="..." +DOWNLOAD="..." +MD5SUM="..." +DOWNLOAD_x86_64="" +MD5SUM_x86_64="" +REQUIRES="" +MAINTAINER="danix" +EMAIL="danix@danix.xyz" +``` + +- Use `DOWNLOAD="UNSUPPORTED"` when no 32-bit source exists +- Use `DOWNLOAD_x86_64` / `MD5SUM_x86_64` for architecture-specific downloads +- Checksums must match the exact source archive +- `REQUIRES=""` if no SBo dependencies; list space-separated SBo names otherwise +- For packages originally authored by others (e.g. Nessus), preserve the + original `MAINTAINER` and `EMAIL` values + +--- + +## `slack-desc` + +- Exactly 11 lines in the `package-name: description` format +- First line: `package-name: package-name (short one-liner)` +- Lines 2–11: description; blank lines use `package-name:` with nothing after +- Do not include the ruler line in the committed file + +--- + +## 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` | + +### Workflow per package + +```bash +# 1. Fix any .info issues automatically +cd <package-name> && sbofixinfo + +# 2. Download sources and verify checksums +# NOTE: when updating to a new version, sbodl will download the source but fail +# because the .info file still has the old (or placeholder) MD5SUM. In that case: +# a) compute the checksum manually: md5sum <source-file> +# b) update MD5SUM in the .info file +# c) run sbodl again — it should now report "md5sum matches OK" +cd <package-name> && sbodl + +# 3. Lint the script and metadata +cd <package-name> && sbolint + +# 4. Build the package +cd <package-name> && sudo bash <package-name>.SlackBuild + +# 5. Lint the built package +cd <package-name> && sbopkglint + +# 6. Remove symlinks created by sbodl before staging +# sbodl creates symlinks in the package directory pointing to downloaded sources. +# These must never be committed to git. +find . -type l -delete + +# 7. Commit +git add <package-name>/ +git commit -m'<package-name>: add version X.Y.Z' +``` + +--- + +## Commit Conventions + +- One commit per package add/update +- Commit message format: + - Add: `<package-name>: add version X.Y.Z` + - Update: `<package-name>: update to X.Y.Z` + - Fix: `<package-name>: fix <short description>` + +--- + +## Maintainer + +danix — danix@danix.xyz @@ -30,7 +30,7 @@ This list is ever growing, if you want to ask for a package to be prioritized, j | cadaver | ✅ | [notroj/cadaver](https://notroj.github.io/cadaver/) | 0.28 | | powershell | ✅ | [microsoft.com](https://www.microsoft.com/powershell/) | 7.6.0 | | Nessus | ✅ | [tenable.com](https://www.tenable.com/downloads/nessus) | 10.11.3 | -| nuclei | ❎ | [projectdiscovery/nuclei](https://github.com/projectdiscovery/nuclei) | 3.7.1 | +| nuclei | ✅ | [projectdiscovery/nuclei](https://github.com/projectdiscovery/nuclei) | 3.7.1 | | windows binaries | ❎ | [kali.org](https://www.kali.org/tools/windows-binaries/) | 0.6.10 | | webshells | ❎ | [kali.org](https://www.kali.org/tools/webshells/) | 1.1 | | metasploit framework | ❎ | [metasploit.com](https://www.metasploit.com/) | 6.4.124 | @@ -43,8 +43,6 @@ This list is ever growing, if you want to ask for a package to be prioritized, j > > There's a metasploit package on slackbuilds.org but is an older version (last updated in 2022). I'll contact the mantainer and ask to transfer it to me and I'll update it. > -> The hydra package on slackbuilds.org refers to version 9.4 and doesn't build anymore on Slackware64-current (as of today 17/03/2026), so I have reported here the build scripts with the updated source for version 9.6 -> > The cadaver package is available on slackbuilds.org but it's for an older version. I've reported here the script and built the newest version. The slackbuild includes now a pull from the [notroj/neon](https://github.com/notroj/neon) repository which is usually not allowed for SlackBuilds that are uploaded to slackbuilds.org > > The Powershell package is the same as the one on slackbuilds.org but builds the latest version available. |