Bash Card Generator — User Guide

0. Bash Cards primer

What they are

Bash Cards are QR-powered, scanner-first Bash programs: each card back holds a full script, while the front carries a Data Matrix input so a scanner can “type” a key or command into the terminal.

They are intentionally tangible — a modern take on punch cards and floppies — so you can carry scripts as physical objects, scan them into air‑gapped boxes, and study how payloads are packed and unpacked.

Mission & ethos

• Built to teach Linux, networks, and security hands-on; every card is a playable demo you activate by scanning.
• Inspired by hacker culture (CDC’s playful rebellion is the sheep cipher); tools should be curious, not careless.
• Publishing model: free to remix under MIT; learn by doing, scan → execute → decode → understand.

Safety & license

• License: MIT — scripts, cards, and text are free to reuse, remix, and ship with attribution.
• Ethics: educational and authorized environments only; you own the risk of where/how you run them.
• Practice safely: decode in sandboxes, review before execution, and prefer containers or disposable VMs.

Deck & inputs

• Three full 52-card decks (156 cards) with a Tarot layer on the first 78 for narrative flavor.
• Back: locked QR payload for the script. Front: Data Matrix cycling through key/command inputs for scanner-driven keyboard control.
• Optimized for 4×6 thermal labels — fast, inkless, field-ready printing.

Encoding & unpacking

• Scripts are gzip-compressed, base64-encoded, then wrapped in a one-liner: bash -c \"$(echo ... | base64 -d | gunzip)\".
• This packaging keeps payloads QR-sized and stable while remaining transparent: you can always decode and inspect.
• To unpack manually: scan to a file, run echo \"BLOB\" | base64 -d | gunzip > unpacked.sh, and read the restored script.

Running a card

• Print → scan the back into a terminal with a QR reader (for example, zbarcam) → the payload reconstructs and runs.
• Use the front-side Data Matrix inputs for stepwise control or command prompts when building larger sequences.
• Some cards assume sudo or network access; review before use and run only on systems you control.

1. Quick start (single card)

1. Paste or import a script into Raw Bash Script.
2. Pick a card slot from the selector at the top of Card Details.
3. Enter a Card title, optional deck name, mana cost, and P/T.
4. Press Describe Script / Suggest Art (or enable the auto-toggles) to fill in rules text and art.
5. Select a Pipeline and click Build Payload into QR Field to produce the encoded QR payload.
6. Review the front and back previews; tweak anything you like.
7. Click Generate Cards then Save to Home Page to store PNGs and metadata.

3. Page layout

The main generator page (index.html) has three zones:

• Left panel — themes, card details, imports, pipelines, ASCII/stego tools, and helpers.
• Center card — live preview of the front (title, art, rules box, P/T, datamatrix).
• Right card — live preview of the back QR code built from the pipeline output.

4. Card details & themes

Theme selector

The Theme box controls the overall UI palette and gives the card itself a subtle hue. QR codes and text remain high‑contrast for printing.

Card details

• Card slot — choose an index from the selector; it ties into the unified deck data.
• Deck name & Card title — what appears at the top of the card.
• Mana cost — shorthand like 3 U R; rendered into mana pips.
• Power / Toughness — the 3/2-style stats in the lower right.
• Rules text — MTG-style text block. This can be auto-generated from a script.

5. Getting scripts into the deck

Direct paste

Paste or type any shell-style code into Raw Bash Script. This is the source for all pipelines.

GitHub import

• Enter a repo (owner/repo or full URL) and optional branch.
• Click Load Repo File List and choose one or more files.
• Click Load Selected GitHub File(s) to pull the contents into Raw Bash Script.

ZIP import

• Upload a ZIP of scripts.
• Select entries in the list and click Load Selected Zip File(s).

6. Auto description & art

The Auto metadata toggles sit inside the Card Details section.

Auto-describe imported script

• When enabled, any GitHub/ZIP load triggers a call to describe.php.
• The backend returns a type line, two abilities, flavor text, and suggested mana/power/toughness.
• If your mana/P/T fields are empty, the suggestions are applied.

Auto-generate card image

• After description, the app calls image.php (using the script, title, and rules as context).
• The result appears in the preview area and is converted into ASCII art in the frame.
• Requests are deduped so the same card state does not generate multiple images accidentally.

7. Pipelines & QR

The Pipeline box controls how your raw script is transformed before it lands in the QR field.

• Plain — uses QR Code Script/URL exactly as you type it.
• gzipb64 — turns the script into gzip+base64 with a one-liner stub that reconstructs restored.sh.
• BC256 modes — convert the script into a terminal-safe byte grid with an accompanying runner.
• Extended modes — additional encodings (raw base64, hex, AES envelope, logo stego, XOR, etc.) enabled by the UI script.

After choosing a mode, click Build Payload into QR Field. The QR preview updates automatically, and very large payloads are chunked into multiple QR blocks.

7.1 Why so many pipelines?

The point is not just “make a QR work” – it is to expose many styles of moving code so that curious users can reverse‑engineer them and recognize those patterns out in the wild.

• Forward path. You start with readable Bash and choose a pipeline. The generator compresses/encodes it and prints a QR.
• Reverse path. Later, you can take the payload from a saved card, decode it step‑by‑step, and see exactly how base64, hex, BC256, or AES envelopes are layered.
• Air‑gap workflows. Instead of SCP or copy/paste, you can open vim/nano on a remote box, scan the card into the editor, and save. The “file transfer” was literally a beam of light.
• Interpreter‑only mode. In many pipelines the QR payload can also be scanned straight into a shell prompt. The script will reconstruct itself and run without ever touching disk, which is useful on locked‑down systems.
• Pattern recognition. Once you have pushed scripts through these modes a few times, you start to recognize them: what raw base64 blobs look like, which stubs rebuild gzip files, how BC256 runners reconstruct a grid. That’s the real lesson.

In other words, the pipelines double as a field manual: they show how people hide, compress, and ship behavior through text‑only channels, and they give you a safe playground to practice unwrapping that behavior from both directions.

7.2 Recognizing packed payloads (defender checklist)

Many real‑world “one‑liner” payloads – including reverse shells – are built with the same tricks you use here. The goal of this section is to help you spot and safely unpack them, not to run them.

• Base64 loaders. Shapes like echo 'LONG_BASE64' | base64 -d | bash are a red flag: the visible part is just a loader, and the real script is hidden in the base64 blob.
• gzip+base64 loaders. Variants that add gunzip (for example, decodes then pipes into gunzip and then into a shell) usually mean “compressed script inside”.
• Hex / numeric blobs. Long strings of hex characters reconstructed with Python/Perl (bytes.fromhex(...), int("0x...",16), etc.) are another common packing style.
• Staged scripts. Short stubs that download or decode a second script, write it to a file, then run it are effectively “installers” for hidden behavior.

To analyze a suspicious payload, work backwards instead of executing it:

• Copy just the encoded blob (base64, hex, etc.) into an isolated environment.
• Use the reverse of the pipeline you see here: base64 -d, gunzip, hex decoders, or the BC256 tools, but direct the output into a file, not into bash.
• Open the restored script in a text editor and review it like any other source code before deciding whether to run it.

By designing and decoding your own Bash Cards pipelines, you train the same instincts: you learn to look past the wrapper and ask “what script is this loader hiding, and do I actually want to run it?”

Reverse‑shell style pattern (pseudocode)

A common malicious pattern is “encoded script that opens a network connection back to an attacker”. In abstract form it often looks like:

# PSEUDOCODE — example shape, not executable
PAYLOAD="LONG_BASE64_OR_HEX_BLOB"
echo "$PAYLOAD" | base64 -d | bash   # decoded script would open a remote connection

The important part to recognize is not the exact command, but the structure:

• A large encoded blob stored in a variable or here‑document.
• A tiny loader that decodes that blob.
• The decoded script then opens a network connection and hands it to a shell.

In Bash Cards you use the same structural idea for legitimate exercises and utilities. The difference is that you keep the decoded script visible and documented, so learners can study how it works instead of treating the blob as a black box.

8. Chunked QR playbook (multi-card payloads)

When a payload is too big for one QR, the generator splits it into a sequence you can print across multiple cards.

• Numbered order. Blocks are labeled QR-01, QR-02, etc. Scan them in that order.
• Wrapper script. Copy the “Rebuild wrapper” textarea; it asks you to scan each card into /tmp/bashcard_chunks.txt and then run the combined payload.
• Preview & sizing. Chunk preview shows character counts and QR density before you print.
• Reader quirks. Chunking keeps cards small enough for scanners that inject line breaks or choke on dense QRs.

9. Basic QR presets

Use the Basic QR Presets panel for non‑Bash QR codes:

• Select a type: URL, Wi‑Fi, Geo, Telephone, SMS, Email, or Text.
• Fill out the fields for that type.
• Click Apply to QR Field; the helper writes the payload into QR Code Script/URL and refreshes the QR preview.

10. Saving, gallery & printing

Save to Home Page

Once you like how the front and back look, just click Save to Home Page. The card is saved on the server and will show up automatically in the viewer on the Gallery page and in the “Saved Cards” strip on the home screen.

Saved Cards (home strip)

• Shows each saved card as a flip-card.
• Click to flip; hover on the back to reveal buttons: View Raw, View QR, and Print.

Gallery

• 3/gallery.html lists all cards from 1/img/cards as flip-cards.
• Click a card to flip between front/back; use the print button to open a 6×4 layout with both sides for a thermal/inkjet pass.

Auto Deck (ZIP)

• 3/Github.html provides a bulk flow: upload a ZIP of scripts and generate a whole deck.

11. Auto Deck (ZIP)

Use 3/Github.html to turn a ZIP of scripts into ready-to-print cards in one pass.

Flow

• Prepare a ZIP of Bash scripts; file names become card titles (numbers and extensions are stripped).
• Upload the ZIP; the page gzips+base64-wraps each script into the standard one-liner payload and builds a card per entry.
• Each card gets a Data Matrix input (keyboard list), poker/Tarot metadata, art ASCII orb, mana/P/T suggestions, and a QR preview with a ~2800‑char limit badge.
• Click any card to flip; use the per-card print button for a two-sided 4×6 print layout.

Why use Auto Deck

• Bulk encode lessons without hand-entering each script in the generator UI.
• Keep cards aligned with the unified 180-slot deck (poker ranks, Tarot, UNO, keyboard/Data Matrix inputs) automatically.
• Validate payload size before printing; the QR badge shows when you are near limits.

12. Bash Cards execution model & script style

Bash Cards are built for scanner‑first, almost wordless scripting. Treat each card like a spell: the QR code is your wand, the terminal is the ritual circle, and the interpreter is the summoned engine that does the work.

10.1 Execution pipeline — from card to shell

This works because the shell happily accepts “one enormous command line” as long as it is syntactically valid. The QR code is just a highly compressed way of getting that one command into the shell.

10.2 Shebang + one‑line payload

• Line 1: shebang. Always start with a real shebang such as #!/bin/bash or #!/usr/bin/env bash. Scanner presses Enter once and the kernel knows which interpreter to launch for saved files.
• Line 2: everything else. Put the entire program on the second line as a single minified command. Join statements with ; or && and avoid blank lines.
• Direct execution mode. If you are encoding bash -c '...payload...' directly in the QR, you can skip the shebang and file permissions entirely — the interpreter is invoked as part of the payload itself.
• Why this helps scanners. A continuous line is resilient to scanners that accidentally send “Enter” once at the end; there are no fragile line‑break boundaries in the middle of your logic.

10.3 Byte‑saving and “wordless” code

Your goal is to express intent with as few visible characters as possible while staying predictable:

• Single‑letter variables. Use tiny identifiers (a, b, x, f) instead of long names. Every extra character is more ink and more QR density.
• Delete noisy words. Remove comments, verbose option names, and long strings. Favor short flags (for example, -y instead of --yes) when they are unambiguous.
• Collapse whitespace. Multiple spaces, tabs, and newlines are mostly cosmetic to the shell. Minimizing them reduces QR size and lowers the chance of OCR/scan software trying to “pretty‑format” your code.
• Chain operators. Combine logic with && / || / ; so you get conditional flows without extra lines: cmd1&&cmd2||cmd3.
• Avoid “suspicious” text where possible. Some security tools and scanners look for human words like “password”, “root”, or “delete”. Encoding these as data (see below) keeps the visual card cleaner and focuses on teaching encodings instead of triggering content filters.

10.4 Encodings: base64, hex, gzip & friends

Instead of writing big readable blocks, store them as numbers and restore them at runtime:

• Base64. Encode a helper script or long string into 64‑character alphabet text. At runtime, base64 -d restores the bytes. Great when terminals and QR readers handle ASCII reliably.
• Hex (base‑16). Represents bytes as 0–9a–f. Hex is easy to inspect and can be decoded with Python or xxd. It is visually dense but regular, which scanners like.
• gzip+base64. Compress first, then encode. This is ideal for large scripts: you trade CPU time at runtime for a smaller QR footprint.
• BC256 / bitmap‑style encodings. Map bytes directly to color indices (like xterm‑256). In Bash Cards, this becomes a teaching tool: the “image” is literally the payload.
• Whitespace stego (advanced). You can hide bits in insignificant whitespace (tabs vs spaces, trailing spaces) or subtle layout. This must be used carefully; many tools normalize whitespace and can destroy the channel, but it is a powerful concept for advanced exercises.

10.5 Steganography & “don’t spook the scanners”

• Hide intent in data, not prose. Instead of writing rm -rf /tmp/something in clear text, store it as an encoded string and reconstruct it into a safer, reviewable script file before execution.
• Distribute meaning. Split multi‑step behavior across encoded blocks (script body, configuration, artwork) so no single visible chunk “looks dangerous” to simple scanners.
• Use neutral vocabulary on the card face. Titles and rules text can focus on the learning goal (“BC256 Encoding Lab”) instead of describing sensitive behavior in plain English.
• Prefer interpreters over direct binaries. Running via bash -c, python -, etc., keeps the QR payload “just a command”, which is less likely to be filtered than embedded binary blobs.

10.6 Self‑saving, permissions, and dependencies

• Self‑saving. A card can write a restored script file (for example, restored.sh) and then either bash restored.sh or chmod +x restored.sh for later reuse.
• Skipping chmod when possible. If you always drive execution via bash restored.sh or bash -c '...', you never need executable bits at all — the interpreter is invoked explicitly.
• Non‑interactive installs. Use fully automated flags (-y, --noconfirm, etc.) for package managers so the card never stalls waiting for keyboard input.
• Fail loudly but safely. When a dependency is missing and cannot be installed, exit with a clear message instead of half‑running. Remember the operator may only see a QR‑driven transcript.

13. AI script generator

The Script Generator section lets you describe what you want in plain language; the backend produces a compact Bash script.

• Enter a prompt describing the behavior (for example, “monitor a log file and alert on failed SSH logins”).
• Click Generate Bash Script.
• The backend creates a non‑destructive, obfuscated Bash script and writes it into Raw Bash Script for you to encode onto a card.

14. Safety notes

15. About & FAQ

• What are Bash Cards? Scannable QR codes that deliver full Bash scripts into a terminal with no typing — each card is a modular utility.
• Bash, shells, interpreters. Bash is the common Linux shell; as an interpreter it reads .sh line by line and executes immediately.
• Side-loading. Running outside repos/app stores; cards are sideloaded via scan straight into a shell prompt.
• Sneakernet. Physical transfer (paper/QR/thermal labels) instead of network; cards are designed to be fully offline.
• QR capacity. Largest standard QR (v40) is ~3 KB binary / ~4.2 K alphanumeric; use chunking or staged loaders for bigger payloads.
• How to use. Scan with a webcam or barcode scanner; it pastes and runs the payload. The same one-liner can also be piped via curl without a scanner.
• Why do this? Hands-free automation, education, and repeatable ops without memorizing commands — fast, reliable, and portable.
• What belongs on cards? Educational scripts, system control, recon/defense tools, simulations, data-transfer commands — any Bash logic.

16. Team & origin

• Sheep cipher. Inspired by Cult of the Dead Cow — humor + rebellion as a signal for curious hacking.
• Physical lineage. Cards echo punch cards, punched tape, and floppies: portable, tangible logic you can shuffle and scan.
• What we build. Beginner Linux decks, recon/defense decks, simulations/gameplay scripts, QR bootables for air-gapped or harsh environments.
• Mission. Hands-free Linux tools disguised as a game — learning by doing, scanning, and executing real commands.
• Why it matters. Hands-on, scanner-first learning lowers friction and makes Bash a playful, physical medium.

17. Security Deck map (scanner threat timeline)

Quick checklist for scanner-to-shell defenses:

• Entry / Guard. All scans hit a gateway that enforces length/charset and dispatches by card identity.
• Schema. Only accept CARD:DECK:SUIT:RANK:PAYLOAD shapes; drop everything else.
• EICAR kill switch. Deliberate AV trigger to abort if malformed input appears.
• Config lock. Block vendor config barcodes; freeze symbologies and options.
• Replay sentinel. Detect cloned cards/token reuse; rate-limit and require nonce/expiry.
• Signed tokens. Replace raw script text with signed/HMAC tokens verified by the rig.
• Shell focus. Scanner never points at root/admin shells; UI/output and admin live on separate ttys.
• Audit & ship gate. Log every scan; alert on anomalies. Missing controls means training-only, not production.

18. Security Deck hardening (rig checklist)

• Scanner gateway. All scans flow into a guard script on a dedicated tty; enforce length/charset and dispatch by deck/suit/rank.
• Strict grammar. Payloads shaped like CARD:DECK:SUIT:RANK:PAYLOAD are allowed; everything else is rejected early.
• Scanner config lock. Only required symbologies enabled; vendor config barcodes are removed/blocked and configs are versioned.
• Scanner profile (from vendor manual). Default to wired HID-KBW; disable unneeded modes (BLE/SPP/2.4G dongle), inventory/batch modes, and ad-hoc upload speed tweaks. Freeze prefixes/suffixes/terminators so attacker scans cannot inject control keys.
• State control. After hardening, save a “user default” snapshot on the scanner and document the config; factory-reset barcodes must be physically restricted.
• Replay & tokens. High-value actions ride on signed/expiring tokens, not raw text; expect nonce/expiry/key id checks.
• Shell focus. Scanner never shares a root shell or admin tty; UI output and admin access are on separate channels.
• Audit trail. Log every scan/offload logs; alert on abnormal rates or patterns.
• Ship gate. If any item above is missing, decks stay training-only; hardened rigs require the full checklist.

19. Scanner controls

• Factory reset. Scan “Factory Default” (SpecCode93) to restore HID-KBW; then apply your profile and “Save as User Default” (SpecCode92).
• Version / battery. SpecCode39 returns version info; SpecCode15 shows battery capacity (~10% tolerance).
• Bluetooth modes. HID (SpecCodeAA + Pairing Setting SpecCode99), BLE (SpecCodeAC), SPP (SpecCodeAB); set a 16-byte Bluetooth name via barcode (append protocol type).
• 2.4G modes. Receiver mode and virtual serial; choose immediate vs inventory (buffered) scans depending on workflow.
• Immediate vs inventory. Immediate streams scans live; Inventory buffers then uploads—toggle per Bluetooth/2.4G mode based on whether you need burst vs batch behavior.
• Upload speed. Manual includes upload-speed barcodes; set slower speeds if the host drops characters, faster for trusted hosts.
• Button shortcuts. Shortcut Functions of Button can be set to “Search Bluetooth HID” (hold 10s to pair) or other pairing/scan behaviors.
• Sleep time. Adjustable sleep timers; pick conservative values to prevent surprise disconnects in kiosks.
• Keyboard language & case. Match host layout; keep case conversion off to avoid mangled payloads.
• Case conversion. Leave disabled unless you intentionally need upper/lower forcing.
• Prefix/suffix/terminators. Standard suffix is Enter; strip unexpected prefixes/suffixes/control keys. Terminator options include Enter, Tab, CRLF, etc.—lock to Enter for Bash Cards.
• Notice settings. Beep/LED vibration options for noisy environments; keep feedback on for operator clarity.
• GS / escape settings. Keep GS character table and escape set at defaults to avoid hidden control characters in payloads.
• Control/displayable tables. Manual includes control character and displayable character tables—useful if you lock down accepted byte ranges.
• Data Matrix deck inputs. Cards cycle through ENTER, SHIFT-ENTER, BACKSPACE, CTRL-C/D/Z/L, arrows, TAB, ESC for scanner-keyboard control.

20. Legal & terms

• As-is. Scripts and cards are provided without warranty; you assume all risk when running them.
• User responsibility. You verify legality, safety, and environment fit; do not run on systems you do not own or administer.
• Educational intent. Bash Cards target ethical/authorized use only; creators are not liable for misuse or damage.
• Trademark & content. Brand assets belong to the creator; user-submitted scripts remain your responsibility.
• Policy updates. Terms can change; continued use implies acceptance of the current terms.