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.**

---

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