path: root/AGENTS.md

# Agent Instructions — Slackware Pentesting Suite

This file governs how AI agents must behave in this repository.
**Read it in full before taking any action.**

**Maintainer workspace:** if this repo is checked out inside the maintainer
workspace (a parent directory holding `AGENTS.md`, `sweep.sh` and `hooks/`),
read `../AGENTS.md` first. It holds the operational workflow: git hooks, the
upstream sweep, test builds, and delivery to SBo.

---

## 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
```

---

## Packages Maintained Elsewhere

Several packages that used to live in this repo are now danix-official on
SlackBuilds.org and maintained in the separate
[sbo-slackbuilds](https://github.com/danixland/sbo-slackbuilds) repo:
`ffuf`, `gobuster`, `nuclei`, `feroxbuster`, `metasploit-framework-bin`,
`SecLists`, and `exploitdb`. Do not modify those packages here; changes
to them belong in `sbo-slackbuilds`.

---

## Package Build Strategies

Before updating or adding a package, identify which build strategy it uses:

| Strategy | Examples | Key indicator |
|----------|----------|---------------|
| Python source | netexec | `python3 -m build`, `python3.SlackBuild` |
| Go source | ffuf, gobuster, nuclei | `go build`, `REQUIRES="google-go-lang"` |
| Autotools/cmake source | hydra, cadaver | `./configure` or `cmake` |
| Binary repack (.deb) | metasploit-framework-bin | `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

`sbofixinfo` does not fix checksums, it only normalizes `.info` formatting.
The checksum loop is `sbodl`:

```bash
# Pass 1: downloads the source and prints
#   WARN: md5sum doesn't match ... got: <new>
cd <package-name> && sbodl

# Put the got: value into MD5SUM (or MD5SUM_x86_64) in the .info file

# Pass 2: 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

Check whether the package is already on SlackBuilds.org as an orphan
(`MAINTAINER="orphaned - no maintainer"`, `EMAIL="NOEMAIL"` in its `.info`,
see https://slackbuilds.org/orphaned_builds_faq/). In the maintainer
workspace run `../sbo-orphans <prgnam>`. If it is orphaned, adopt it: start
from the SBo build, set `MAINTAINER`/`EMAIL` to danix's details, and adopt
any orphaned deps in its `REQUIRES` too. Do not write a new build from
scratch.

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, see above), then `sbolint`.
4. Report results and wait for commit instruction.

---

## Version Tracking: nvchecker.toml

`.extras/nvchecker.toml` is the **suite catalog**: it tracks upstream versions
for every tool in the suite, not only the packages in this repo. That
includes packages maintained in `sbo-slackbuilds` and tools packaged on SBo by
others (e.g. `hashcat`, `john`). Stanzas without a package directory here are
intentional; do not remove them. New packages get a stanza too.

The file has no `[__config__]`. Do not run it as-is against GitHub: the
anonymous API budget (60 req/h) runs out and later stanzas 403. Run it from a
throwaway copy with a `[__config__]` that adds a GitHub token keyfile, and
probe single stanzas with `nvchecker -c <cfg> -e <name>`. Prefer
`use_latest_release` over `use_max_tag` for github stanzas; `use_max_tag` is
tightly rate-limited and only needed for repos that tag without cutting
Releases.

Maintainer tooling (git hooks, the upstream sweep, test builds, SBo archive
builder) is kept outside this repo, in the maintainer's private workspace.

---

## SlackBuild Scripting Rules

### Templates (source of truth)

Local templates live in `~/Templates/SlackBuilds/`. Always start from the
matching template there rather than writing a SlackBuild or its accompanying
files from scratch. The directory holds per-build-type SlackBuild templates
(`autotools-template.SlackBuild`, `cmake-template.SlackBuild`,
`go-template.SlackBuild`, `python-template.SlackBuild`, etc.) and shared
support files (`slack-desc`, `template.info`, `doinst.sh`, `README`).

When the local template and the upstream SBo template disagree, the local one
wins. Only fall back to the [SBo template](https://slackbuilds.org/templates/)
if no local template fits.

The `sbo/` and `conraid/` subdirectories are git clones kept up to date by
`~/Templates/SlackBuilds/update-templates.sh`. Run that script (or let the
desktop autostart handle it) before starting work on a new package to ensure
templates reflect the latest upstream conventions.

### Copyright line

In every `.SlackBuild`, the maintainer copyright line is exactly:

```
# Copyright <year> danix <danix@danix.xyz>
```

### General rules

- Base all scripts on the local templates above; fall back to 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 -not -path './.git/*' -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>`