Week 4: Python requests, argparse, logging, exit codes (Tool v0.1)

First tool-engineering week. You build Tool v0.1, the first version of your SB6141 CSRF tool. v0.1's only job is to FINGERPRINT the target: probe http://192.168.100.1/, verify the response identifies an SB6141, and refuse to do anything else.

Theme

A vulnerability-research tool that runs against any IP without first checking what the target is, is a tool that will eventually run against the wrong target. Tool v0.1 makes the safety property non-optional: the tool's first action is fingerprint, and if the fingerprint does not match an SB6141 the tool exits with a clear error and does not proceed. The pattern is the foundation every later version inherits.

The Python skills this week are not new. FND-102 introduced requests, argparse, logging, and exit codes. ADV-101 applies them with a specific discipline: the tool's argparse is the user-facing contract; the logging is the audit trail; the exit codes are the machine-readable success/failure signal. Every choice in the tool's interface should be defensible at the capstone defense.

Tool v0.1 is intentionally minimal. It takes one argument (--target IP) and one optional flag (--help). It issues one HTTP request. It checks the response for an SB6141-specific marker. It prints a single-line result and exits with a clear status code. That is all it does. Subsequent versions add the destructive-action plumbing, the authorization gate, the dry-run preview, the structured logging, the idempotency, and the rollback. v0.1 is the safety floor.

By the end of Week 4 you have a Python CLI tool that probes the SB6141 administrative interface, identifies it as an SB6141 (or refuses), and that you can re-run any time as a non-destructive verification.

Schneier weave (~270 words, A Hacker's Mind Ch 9)

Schneier devotes Chapter 9 of A Hacker's Mind to the question of safety controls in adversarial systems. His worked examples include nuclear-weapons two-person-rule procedures (no single operator can launch), commercial-aviation checklists (every action verified by two pilots), and financial-system transaction confirmations (no large transfer without a second authorization). Across the three, the pattern is the same: systems with high-cost failure modes embed safety controls that REQUIRE multiple independent signals before consequential action.

Tool v0.1 introduces the first of these signals in the SB6141 CSRF tool: the fingerprint. Before any state-changing action (none in v0.1; many in v0.2+), the tool independently verifies that the target IS what the operator believes it to be. The verification is unauthenticated probe (a GET to /); the marker is unique-enough (an SB6141 page-title string, a version-banner regex); the failure mode is FAIL CLOSED (refuse to proceed if the marker is absent or ambiguous).

Schneier's argument is that safety controls work when they cost less than the failure they prevent. The two-person rule is cheap (a few seconds of coordination); the failure it prevents (a unilaterally launched nuclear strike) is catastrophic. The aviation checklist is cheap (seconds per item); the failure it prevents (a crashed airliner) is fatal. The fingerprint is cheap (one HTTP request); the failure it prevents (a tool destructive-action run against the wrong target) is the difference between a paper at DEF CON and a CFAA prosecution.

The discipline of building safety controls FIRST, before the dangerous capabilities they protect against, is the engineering discipline that distinguishes professional vulnerability research from script-kid enthusiasm. Tool v0.1 is the smallest possible expression of that discipline.

Reading list (~1 hour)

1. Schneier, A Hacker's Mind, Ch 9 ("Hacking Safety Systems"). Academy library; calibre id 677.
2. Seitz + Arnold, Black Hat Python 2nd ed., Ch 6 (intro to requests-based tool engineering). Academy library; calibre id 138. Pages cited at the chapter-topic level only; library copy's PDF extraction is unreliable for verbatim quoting.
3. Python requests documentation: Quickstart at https://requests.readthedocs.io/en/latest/user/quickstart/. FND-102 introduced this; ADV-101 revisits in the safety-control context.
4. Python argparse documentation: Tutorial at https://docs.python.org/3/howto/argparse.html. Same; revisit.
5. The Open Source CSRF tool ecosystem. Skim three open-source CSRF reproduction tools on GitHub. Look for which ones have --target arguments; which fingerprint; which proceed unconditionally. The variation is instructive.

Lecture outline (~50 min)

Part 1: The Tool v0.1 contract (15 min)

• Inputs. One required argument: --target IP_OR_HOSTNAME. One optional flag: --help. Nothing else in v0.1.
• Behavior. Issue one HTTP GET to http://<target>/. Inspect the response. Decide: is this an SB6141? Print the answer; exit with status 0 if SB6141, status 3 if not.
• Output. Exactly two formats: success (SB6141 detected at <target>; firmware version <Y>) or failure (Error: target at <target> does not fingerprint as SB6141; got <observed marker>). One line; structured enough to be grep-able.
• Exit codes. 0 = SB6141 detected; 1 = runtime error (network unreachable; timeout); 2 = usage error (missing argument); 3 = fingerprint mismatch (target reachable but not SB6141).
• What v0.1 does NOT do. No destructive action. No --authorized-by (yet). No --dry-run (yet; though the entire tool is, in effect, a non-destructive probe). No log file output yet.

Part 2: Fingerprinting the SB6141 (15 min)

• The signal. The SB6141 administrative interface at http://192.168.100.1/ returns an HTML page with identifying strings. The exact strings vary by firmware version; common markers include:
  • HTML <title> containing SB6141 (most firmware versions)
  • A version-banner in a <div> or <span> (e.g., <span>SB6141 Hardware Version: 7</span>)
  • An HTTP Server: header set to a specific value (rarely; consumer devices often hide this)
• Strategy. Look for two independent markers; require BOTH to match before declaring SB6141. A single-marker check is too easy to spoof or coincide-match; two-marker is more defensible.
• The fingerprint code (sketch).

  import re
  import requests
  
  TITLE_MARKER = re.compile(r'SB6141', re.IGNORECASE)
  VERSION_MARKER = re.compile(r'SB6141\s+Hardware\s+Version', re.IGNORECASE)
  
  def fingerprint(target: str, timeout: float = 5.0) -> dict:
      url = f'http://{target}/'
      try:
          resp = requests.get(url, timeout=timeout)
      except requests.exceptions.RequestException as e:
          return {'match': False, 'reason': f'request failed: {e}'}
      title_hit = bool(TITLE_MARKER.search(resp.text))
      version_hit = bool(VERSION_MARKER.search(resp.text))
      if title_hit and version_hit:
          return {'match': True, 'firmware_hint': _extract_firmware(resp.text)}
      return {'match': False, 'reason': f'title_hit={title_hit} version_hit={version_hit}'}
  
  

• _extract_firmware parses the version banner for the specific firmware version (useful for downstream tool versions that have firmware-conditional behavior).

Part 3: Argparse hygiene (10 min)

• Help strings read like documentation. Not '--target: IP' but '--target: IP address of the SB6141 admin interface (default: 192.168.100.1; required)'.
• prog and description matter. The argparse description is the first thing a user reads at --help; make it informative.
• type= is the validator. type=str is fine for hostnames; type=int for ports. For more complex validation (IP-only; CIDR ranges) write a custom callable.
• epilog is for examples. A multi-line epilog showing one or two example invocations dramatically improves --help usability.
• %(prog)s and %(default)s in help strings auto-substitute at format time; use them.

Part 4: Logging at the v0.1 level (10 min)

• v0.1 logging is light: stderr only. The structured-JSON file logging arrives in v0.3 (Week 7). v0.1 emits human-readable log lines to stderr at INFO level by default.
• logging.basicConfig is enough for v0.1.

  import logging
  logging.basicConfig(level=logging.INFO, format='%(asctime)s %(levelname)s %(message)s', stream=sys.stderr)
  
  

• What v0.1 logs. "Probing target X"; "Response received (HTTP 200)"; "Fingerprint match" or "Fingerprint mismatch (reason: Y)"; "Exiting with status N".
• What v0.1 does NOT log. The full response body (could be large); cookies or sensitive headers; anything PII (none expected from the SB6141, but the discipline transfers).

Disclosure-Ethics Sidebar

The "non-destructive probe" framing matters because some legal theories under CFAA argue that even unauthorized read-only access is a violation. The defense for academy lab work is the documented authorization; the defense for hypothetical at-home use of v0.1 is that the student owns the device. Both must be true; the discipline is to never act without one of them.

Labs (~3 hr)

Lab 4: Tool v0.1, Fingerprint Only (labs/lab-4-tool-v01.md)

• Goal: ship sb6141_csrf/v01.py (Tool v0.1): probes the target; fingerprints as SB6141 or refuses; clean argparse + exit codes
• Time: ~3 hr
• Artifact: lab-4/sb6141_csrf/v01.py + tests + README stub in ~/adv-101/lab-4/

Independent practice (~5 hr)

1. Read 5 open-source CSRF or scanning tools on GitHub (1.5 hr). Examples: csrf-payload from Spencer McIntyre; xsstrike; dirsearch; any cable-modem-focused scanner. For each: does it fingerprint? Does it have an --authorized-by-style flag (rare; reflect)? Does its argparse --help read like documentation?
2. Build a "probe me back" mock server (1.5 hr). Write a tiny Python http.server subclass that serves a fake SB6141 page (HTML with <title>SB6141 Cable Modem</title> and the version banner). Use it to test Tool v0.1 without needing the physical modem. The mock server is also useful for writing unit tests in the capstone phase.
3. Argparse hygiene refactor (1 hr). Take one of your FND-102 lab tools; refactor the argparse interface to ADV-101 hygiene level. Notice the gap; the FND-102 tools were good-enough for course work but not capstone-defensible. Tool v1.0 will be capstone-defensible from the start.
4. Schneier A Hacker's Mind Ch 10 (45 min). Continues the safety-systems framing; cited in Week 5.
5. Read Seitz + Arnold Black Hat Python Ch 6 (45 min). The proxy/fingerprint chapter. Not for quotation (PDF extraction unreliable); for the practitioner-voice and the structural-pattern register.

Reflection prompts (~30 min)

1. Your Tool v0.1 takes one argument (--target). Why not two (--target IP --port PORT)? Defend the choice.
2. The fingerprint check uses two independent markers (title + version banner). What is the threat model for "spoofed marker by an attacker who set up a fake SB6141 honeypot"? Is two markers enough?
3. Exit code 3 means "fingerprint mismatch." A wrapper script (a future capstone-defense panelist might write one) sees exit code 3 and... does what? What semantic does the exit code carry?
4. The lecture said v0.1 does NOT have an --authorized-by flag. Why? When does it become necessary?
5. One thing from this week you want to know more about?

Adversary Diary (Week 4)

New entries:

• Python requests library at https://requests.readthedocs.io/. The HTTP client.
• Python argparse module at https://docs.python.org/3/library/argparse.html. The CLI parser.
• Python logging module at https://docs.python.org/3/library/logging.html. The audit-trail backbone.
• The Python http.server module at https://docs.python.org/3/library/http.server.html. Useful for writing mock servers to test against without hardware.
• pytest revisited at https://docs.pytest.org/. v0.1 has a small test suite; v1.0 has a deep one.

What would a reviewer ask?

1. "Show me what your tool prints when I run it against an IP that is NOT an SB6141. Is the message clear?"
2. "Your fingerprint uses two markers. Why two? Why not three? Why not one?"
3. "If the SB6141 vendor updated the admin-page HTML in a future firmware (say, removed the version banner), what would happen to your tool? How would you fix it?"

What comes next

Week 5 introduces tool safety engineering I: the --authorized-by required-flag pattern and --dry-run mode. Tool v0.2 adds these on top of v0.1's fingerprint, and adds destructive-action capability (the CSRF reproduction itself) gated behind both safety controls. v0.2 is the first version that CAN do something destructive; the safety controls are what make it acceptable that it can.