Skip to content

packaging.md

Latest commit

 

History

History
132 lines (97 loc) · 4.14 KB

packaging.md

File metadata and controls

132 lines (97 loc) · 4.14 KB
Raw

Packaging Guide

Debian / Kali / Parrot

Building the Package

# Install build dependencies
sudo apt install debhelper golang-go

# Build the package
dpkg-buildpackage -us -uc -b

# Install
sudo dpkg -i ../procscope_*.deb

Package Layout

debian/
├── control          # Package metadata, deps, description
├── rules            # Build rules (dh + go build)
├── changelog        # Package changelog
├── copyright        # Machine-readable copyright (DEP-5)
├── watch            # Upstream version tracking
├── source/format    # 3.0 (quilt)
└── tests/
    ├── control          # DEP-8 autopkgtest definitions
    ├── cli-sanity       # Verify version string + core CLI help
    ├── install-layout   # Verify shipped manpage + completions
    └── runtime-smoke    # Launch-mode smoke test on root+BTF hosts

The Debian package builds the BPF object from bpf/procscope.c with clang. Prepare vendored source using make source-dist before an offline package build.

Current DEP-8 Coverage

The in-tree autopkgtests now cover three different review concerns:

  • cli-sanity: package version wiring and top-level CLI UX
  • install-layout: binary, man page, and shell completion installation paths
  • runtime-smoke: launch mode on kernels that provide root access and BTF

The runtime smoke test is intentionally guarded so unsupported CI kernels do not create false negatives for packaging review.

Kali Tool Submission

The repository is structured to support a Kali package request and Debian-style sponsorship work. Keep the request grounded in current packaging evidence, not aspirational install commands.

Required Field Value
Name procscope
Homepage https://github.com/Mutasem-mk4/procscope
License MIT
Description Process-scoped runtime investigation tool using eBPF
Similar tools strace, ltrace, sysdig
Activity Active development
Current install path GitHub release asset or make build
Usage sudo procscope -- ./binary

Before opening Kali packaging outreach, have these artifacts ready:

  • dpkg-buildpackage -us -uc -b output from a Debian-family host
  • lintian results with any remaining warnings explained
  • autopkgtest results for the DEP-8 suite
  • one short runtime transcript showing procscope --out ... -- /bin/true

Parrot Contribution

Parrot follows a Debian-oriented packaging flow closely enough that the Debian package quality is the main gate. Finish Debian package validation first, then open maintainer outreach with package build logs and a short smoke test transcript.

Arch Linux / BlackArch

Building the Package

cd arch/
makepkg -si

PKGBUILD Notes

  • Follows Arch Go packaging guidelines
  • Compiles the BPF object from source with clang
  • Offline builds require the vendored source distribution from make source-dist; Debian rules disable Go network access
  • Respects system build flags
  • Installs to standard paths (/usr/bin, /usr/share/man, /usr/share/licenses)

BlackArch Submission

Prepare the PKGBUILD as if it will be reviewed by Arch maintainers first:

  1. Fork the BlackArch repository
  2. Regenerate arch/.SRCINFO
  3. Run makepkg and namcap
  4. Add the package to the appropriate category (blackarch-forensic or blackarch-debugging)
  5. Submit pull request

Release Process

Version Tagging

git tag -a vX.Y.Z -m "Release vX.Y.Z"
git push origin vX.Y.Z

GoReleaser

goreleaser release --clean

This creates:

  • Linux binaries (amd64, arm64)
  • Checksums
  • Release notes from CHANGELOG.md

Manual Release Checklist

  1. Update CHANGELOG.md
  2. Run release preflight checks: python scripts/release_preflight.py --tag vX.Y.Z
  3. Sync Arch metadata when arch/PKGBUILD changes: ./scripts/sync_arch_srcinfo.sh
  4. Build and smoke test on Linux: make build && sudo ./bin/procscope -- /bin/true
  5. Build Debian package: dpkg-buildpackage -us -uc -b
  6. Build Arch package: cd arch && makepkg -sf
  7. Tag the release
  8. Run goreleaser release
  9. Upload artifacts to GitHub release
  10. Update documentation if needed