flag-capturer 0.1.6__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,5 @@
1
+ """flag_capturer - dig CTF flags out of files and strings, through layers of encoding."""
2
+ from .finder import Hit, Finder, scan_bytes
3
+
4
+ __version__ = "0.1.6"
5
+ __all__ = ["Hit", "Finder", "scan_bytes", "__version__"]
@@ -0,0 +1,3 @@
1
+ from .cli import main
2
+
3
+ raise SystemExit(main())
flag_capturer/cli.py ADDED
@@ -0,0 +1,115 @@
1
+ from __future__ import annotations
2
+
3
+ import argparse
4
+ import json
5
+ import os
6
+ import sys
7
+
8
+ from . import __version__
9
+ from .finder import Finder
10
+
11
+ BANNER = "\n >> flag_capturer v{v} - peel the layers, grab the flag\n"
12
+
13
+
14
+ def _enable_windows_ansi():
15
+ """Old Windows consoles (PowerShell 5.1) print colour codes as junk unless asked nicely."""
16
+ if os.name != "nt":
17
+ return True
18
+ try:
19
+ import ctypes
20
+ k = ctypes.windll.kernel32
21
+ h = k.GetStdHandle(-11)
22
+ mode = ctypes.c_uint32()
23
+ if not k.GetConsoleMode(h, ctypes.byref(mode)):
24
+ return False
25
+ return bool(k.SetConsoleMode(h, mode.value | 0x0004))
26
+ except Exception:
27
+ return False
28
+
29
+
30
+ def _color(on):
31
+ if not on or os.environ.get("NO_COLOR") or not _enable_windows_ansi():
32
+ return lambda s, c: s
33
+ codes = {"g": "32;1", "d": "2", "y": "33", "r": "31"}
34
+ return lambda s, c: f"\033[{codes[c]}m{s}\033[0m"
35
+
36
+
37
+ def _targets(paths, max_size):
38
+ for p in paths:
39
+ if p == "-":
40
+ yield "<stdin>", sys.stdin.buffer.read()
41
+ elif os.path.isdir(p):
42
+ for root, _, files in os.walk(p):
43
+ for f in sorted(files):
44
+ fp = os.path.join(root, f)
45
+ try:
46
+ if os.path.getsize(fp) <= max_size:
47
+ with open(fp, "rb") as fh:
48
+ yield fp, fh.read()
49
+ except OSError:
50
+ continue
51
+ elif os.path.isfile(p):
52
+ if os.path.getsize(p) > max_size:
53
+ print(f"skip {p}: larger than --max-size", file=sys.stderr)
54
+ continue
55
+ with open(p, "rb") as fh:
56
+ yield p, fh.read()
57
+ else:
58
+ print(f"not found: {p}", file=sys.stderr)
59
+
60
+
61
+ def main(argv=None) -> int:
62
+ ap = argparse.ArgumentParser(
63
+ prog="flag_capturer",
64
+ description="Dig CTF flags out of files or strings through layers of encoding "
65
+ "(base64/32/85, hex, binary, rot, xor, gzip/zlib, zip ...).")
66
+ ap.add_argument("targets", nargs="*", help="files or folders to scan (default: current folder), '-' for stdin")
67
+ ap.add_argument("-s", "--string", action="append", default=[], help="scan this text directly")
68
+ ap.add_argument("-p", "--prefix", action="append", default=[],
69
+ help="extra flag prefix, e.g. -p DUCTF -p picoCTF")
70
+ ap.add_argument("-r", "--regex", help="your own flag regex (Python syntax)")
71
+ ap.add_argument("-d", "--depth", type=int, default=5, help="max decoding layers (default 5)")
72
+ ap.add_argument("--max-nodes", type=int, default=20000, help="search budget per target")
73
+ ap.add_argument("--max-size", type=int, default=50, help="skip files bigger than N MB (default 50)")
74
+ ap.add_argument("--no-xor", action="store_true", help="skip single-byte xor brute force")
75
+ ap.add_argument("--loose", action="store_true", help="also match any WORD{...} pattern")
76
+ ap.add_argument("--json", action="store_true", help="machine-readable output")
77
+ ap.add_argument("-q", "--quiet", action="store_true", help="print flags only")
78
+ ap.add_argument("-V", "--version", action="version", version=f"flag_capturer {__version__}")
79
+ a = ap.parse_args(argv)
80
+
81
+ if not a.targets and not a.string:
82
+ # nothing given: read piped input, otherwise scan the folder you're standing in
83
+ a.targets = ["."] if sys.stdin.isatty() else ["-"]
84
+
85
+ paint = _color(sys.stdout.isatty() and not a.json)
86
+ if not (a.quiet or a.json):
87
+ print(paint(BANNER.format(v=__version__), "d"))
88
+
89
+ items = [(f"<string {i + 1}>", s.encode()) for i, s in enumerate(a.string)]
90
+ items_iter = list(items) + list(_targets(a.targets, a.max_size * 1024 * 1024))
91
+ found = []
92
+ if not (a.quiet or a.json):
93
+ print(paint(f"scanning {len(items_iter)} file(s)/string(s) ...", "d"))
94
+ for source, data in items_iter:
95
+ f = Finder(prefixes=a.prefix, regex=a.regex, max_depth=a.depth,
96
+ max_nodes=a.max_nodes, xor=not a.no_xor, loose=a.loose)
97
+ hits = f.scan(data, source)
98
+ found += hits
99
+ if a.json:
100
+ continue
101
+ for h in hits:
102
+ if a.quiet:
103
+ print(h.flag)
104
+ else:
105
+ print(paint("[+] ", "g") + paint(h.flag, "g"))
106
+ print(paint(f" {h.source} via {h.path()}", "d"))
107
+
108
+ if a.json:
109
+ print(json.dumps([{"flag": h.flag, "source": h.source, "chain": h.chain} for h in found],
110
+ ensure_ascii=False, indent=2))
111
+ elif not found:
112
+ # always say so (on stderr in quiet mode) so silence never looks like a crash
113
+ print(paint("[-] no flag found. try --loose, -p <PREFIX>, or a bigger -d", "y"),
114
+ file=sys.stderr if a.quiet else sys.stdout)
115
+ return 0 if found else 1
@@ -0,0 +1,195 @@
1
+ """Small, dependency-free decoders. Each takes bytes and returns bytes or None."""
2
+ from __future__ import annotations
3
+
4
+ import base64
5
+ import bz2
6
+ import gzip
7
+ import lzma
8
+ import re
9
+ import zlib
10
+ from urllib.parse import unquote_to_bytes
11
+
12
+ PRINTABLE = bytes(range(32, 127)) + b"\t\n\r"
13
+ _WS = re.compile(rb"\s+")
14
+
15
+
16
+ def printable_ratio(b: bytes) -> float:
17
+ if not b:
18
+ return 0.0
19
+ return 1 - len(b.translate(None, PRINTABLE)) / len(b)
20
+
21
+
22
+ def _b64(b):
23
+ s = _WS.sub(b"", b)
24
+ if len(s) < 8 or not re.fullmatch(rb"[A-Za-z0-9+/]+={0,2}", s):
25
+ return None
26
+ s = s.rstrip(b"=")
27
+ if len(s) % 4 == 1:
28
+ return None
29
+ try:
30
+ return base64.b64decode(s + b"=" * (-len(s) % 4), validate=True)
31
+ except Exception:
32
+ return None
33
+
34
+
35
+ def _b64url(b):
36
+ s = _WS.sub(b"", b)
37
+ if len(s) < 8 or not re.fullmatch(rb"[A-Za-z0-9_-]+={0,2}", s) or not re.search(rb"[-_]", s):
38
+ return None
39
+ s = s.rstrip(b"=")
40
+ try:
41
+ return base64.urlsafe_b64decode(s + b"=" * (-len(s) % 4))
42
+ except Exception:
43
+ return None
44
+
45
+
46
+ def _b32(b):
47
+ s = _WS.sub(b"", b).upper()
48
+ if len(s) < 8 or not re.fullmatch(rb"[A-Z2-7]+=*", s):
49
+ return None
50
+ s = s.rstrip(b"=")
51
+ try:
52
+ return base64.b32decode(s + b"=" * (-len(s) % 8))
53
+ except Exception:
54
+ return None
55
+
56
+
57
+ def _b85(b):
58
+ s = _WS.sub(b"", b)
59
+ if len(s) < 10:
60
+ return None
61
+ try:
62
+ return base64.b85decode(s)
63
+ except Exception:
64
+ return None
65
+
66
+
67
+ def _a85(b):
68
+ s = _WS.sub(b"", b)
69
+ if not (s.startswith(b"<~") and s.endswith(b"~>")):
70
+ return None
71
+ try:
72
+ return base64.a85decode(s, adobe=True)
73
+ except Exception:
74
+ return None
75
+
76
+
77
+ def _hex(b):
78
+ s = re.sub(rb"0x|\\x|[\s:,]", b"", b)
79
+ if len(s) < 8 or len(s) % 2 or not re.fullmatch(rb"[0-9a-fA-F]+", s):
80
+ return None
81
+ return bytes.fromhex(s.decode())
82
+
83
+
84
+ def _binary(b):
85
+ s = _WS.sub(b"", b)
86
+ if len(s) < 16 or len(s) % 8 or not re.fullmatch(rb"[01]+", s):
87
+ return None
88
+ return int(s, 2).to_bytes(len(s) // 8, "big")
89
+
90
+
91
+ def _decimal(b):
92
+ if not re.fullmatch(rb"\s*\d{1,3}(?:[\s,]+\d{1,3}){3,}\s*", b):
93
+ return None
94
+ nums = [int(x) for x in re.findall(rb"\d+", b)]
95
+ if max(nums) > 255:
96
+ return None
97
+ return bytes(nums)
98
+
99
+
100
+ def _octal(b):
101
+ if not re.fullmatch(rb"\s*[0-7]{3}(?:[\s,]+[0-7]{3}){3,}\s*", b):
102
+ return None
103
+ nums = [int(x, 8) for x in re.findall(rb"[0-7]{3}", b)]
104
+ if max(nums) > 255:
105
+ return None
106
+ return bytes(nums)
107
+
108
+
109
+ def _url(b):
110
+ if not re.search(rb"%[0-9a-fA-F]{2}", b):
111
+ return None
112
+ return unquote_to_bytes(b)
113
+
114
+
115
+ _ROT13 = bytes.maketrans(
116
+ b"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz",
117
+ b"NOPQRSTUVWXYZABCDEFGHIJKLMnopqrstuvwxyzabcdefghijklm",
118
+ )
119
+
120
+
121
+ def _rot13(b):
122
+ return b.translate(_ROT13) if re.search(rb"[A-Za-z]", b) else None
123
+
124
+
125
+ def _reverse(b):
126
+ return b[::-1]
127
+
128
+
129
+ def _gzip(b):
130
+ if not b.startswith(b"\x1f\x8b"):
131
+ return None
132
+ try:
133
+ return gzip.decompress(b)
134
+ except Exception:
135
+ return None
136
+
137
+
138
+ def _zlib(b):
139
+ if len(b) < 2 or b[0] != 0x78 or b[1] not in (0x01, 0x5E, 0x9C, 0xDA):
140
+ return None
141
+ try:
142
+ return zlib.decompress(b)
143
+ except Exception:
144
+ return None
145
+
146
+
147
+ def _bz2(b):
148
+ if not b.startswith(b"BZh"):
149
+ return None
150
+ try:
151
+ return bz2.decompress(b)
152
+ except Exception:
153
+ return None
154
+
155
+
156
+ def _lzma(b):
157
+ if not (b.startswith(b"\xfd7zXZ") or b.startswith(b"\x5d\x00\x00")):
158
+ return None
159
+ try:
160
+ return lzma.decompress(b)
161
+ except Exception:
162
+ return None
163
+
164
+
165
+ # (name, function, strict). Strict decoders only fire on input that really looks
166
+ # like their format, so their output is always followed up; loose ones are only
167
+ # followed when the result looks like text.
168
+ DECODERS = [
169
+ ("base64", _b64, True),
170
+ ("base64url", _b64url, True),
171
+ ("base32", _b32, True),
172
+ ("hex", _hex, True),
173
+ ("binary", _binary, True),
174
+ ("decimal", _decimal, True),
175
+ ("octal", _octal, True),
176
+ ("ascii85", _a85, True),
177
+ ("gzip", _gzip, True),
178
+ ("zlib", _zlib, True),
179
+ ("bz2", _bz2, True),
180
+ ("lzma", _lzma, True),
181
+ ("base85", _b85, False),
182
+ ("url", _url, False),
183
+ ("rot13", _rot13, False),
184
+ ("reverse", _reverse, False),
185
+ ]
186
+
187
+ # substrings worth cutting out of a longer text and trying on their own
188
+ CARVERS = [
189
+ re.compile(rb"[A-Za-z0-9+/]{16,}={0,2}"),
190
+ re.compile(rb"[A-Za-z0-9_-]{16,}={0,2}"),
191
+ re.compile(rb"[A-Z2-7]{16,}={0,6}"),
192
+ re.compile(rb"(?:[0-9a-fA-F]{2}){8,}"),
193
+ re.compile(rb"(?:[01]{8}\s?){4,}"),
194
+ re.compile(rb"<~.+?~>", re.S),
195
+ ]
@@ -0,0 +1,239 @@
1
+ """Breadth-first search through decodings until something looks like a flag."""
2
+ from __future__ import annotations
3
+
4
+ import heapq
5
+ import io
6
+ import itertools
7
+ import re
8
+ import zipfile
9
+ from dataclasses import dataclass, field
10
+
11
+ from .decoders import CARVERS, DECODERS, printable_ratio
12
+ from .pe_constants import encoded_constants
13
+ from .fragments import assembly_literals
14
+
15
+ DEFAULT_PREFIXES = ["flag", "ctf", "htb", "thm"]
16
+ _BODY = re.compile(rb"\{[^{}\x00-\x1f\x7f-\xff]{1,200}\}")
17
+ _WORD_END = re.compile(rb"[A-Za-z0-9_]{1,20}$")
18
+ # a believable flag: a 3+ letter word (letters/digits/_) then a body with no spaces
19
+ _LOOKS_LIKE = re.compile(r"[A-Za-z][A-Za-z0-9_]{2,19}\{[!-|~]{4,200}\}")
20
+ XOR_LIMIT = 8 * 1024 * 1024
21
+ _XOR_TABLES = [bytes(c ^ k for c in range(256)) for k in range(256)]
22
+ _LOWER = b"abcdefghijklmnopqrstuvwxyz"
23
+ _UPPER = _LOWER.upper()
24
+ _ROT_TABLES = {
25
+ n: bytes.maketrans(_LOWER + _UPPER, _LOWER[n:] + _LOWER[:n] + _UPPER[n:] + _UPPER[:n])
26
+ for n in range(1, 26)
27
+ }
28
+ _ROT47 = bytes.maketrans(bytes(range(33, 127)), bytes(range(80, 127)) + bytes(range(33, 80)))
29
+
30
+
31
+ class _Queue:
32
+ """Shallow and readable first, so junk decodings can't starve the real lead."""
33
+
34
+ def __init__(self):
35
+ self._h, self._n = [], itertools.count()
36
+
37
+ def append(self, item):
38
+ b, chain = item[0], item[1]
39
+ heapq.heappush(self._h, (len(chain), -round(printable_ratio(b[:4096]), 2), next(self._n), item))
40
+
41
+ def popleft(self):
42
+ return heapq.heappop(self._h)[-1]
43
+
44
+ def __bool__(self):
45
+ return bool(self._h)
46
+
47
+
48
+ @dataclass
49
+ class Hit:
50
+ flag: str
51
+ chain: list = field(default_factory=list)
52
+ source: str = ""
53
+
54
+ def path(self) -> str:
55
+ return " -> ".join(self.chain) if self.chain else "plain"
56
+
57
+
58
+ class Finder:
59
+ def __init__(self, prefixes=None, regex=None, max_depth=5, max_nodes=20000,
60
+ xor=True, loose=False, min_string=6):
61
+ prefixes = [p.rstrip("{") for p in (prefixes or [])]
62
+ self.ctf_like = ("ctf",)
63
+ self.prefix_set = set(DEFAULT_PREFIXES) | {p.lower() for p in prefixes}
64
+ self.custom = re.compile(regex.encode()) if regex else None
65
+ self.loose = loose
66
+ # xor signatures: xor of neighbouring bytes doesn't depend on the key
67
+ sigs = {}
68
+ for p in DEFAULT_PREFIXES + prefixes:
69
+ for v in {p, p.lower(), p.upper(), p.capitalize()}:
70
+ n = (v + "{").encode()
71
+ sigs[bytes(n[k] ^ n[k - 1] for k in range(1, len(n)))] = n[0]
72
+ self.xor_sigs = sigs
73
+ self.prefix_bytes = sorted({(v + "{").encode() for p in DEFAULT_PREFIXES + prefixes
74
+ for v in (p, p.lower(), p.upper(), p.capitalize())})
75
+ self.max_depth = max_depth
76
+ self.max_nodes = max_nodes
77
+ self.xor = xor
78
+ self.min_string = min_string
79
+ self.hits: dict = {}
80
+ self.maybe: dict = {} # WORD{...} with an unknown prefix
81
+
82
+ # ---------- matching ----------
83
+ def _ok_prefix(self, word):
84
+ w = word.lower()
85
+ return w.endswith(self.ctf_like) or w in self.prefix_set
86
+
87
+ def _match(self, b, chain, source, guessed=False):
88
+ if b"{" in b:
89
+ # start from each brace (cheap) and look back for the prefix word
90
+ for m in _BODY.finditer(b):
91
+ start = m.start()
92
+ w = _WORD_END.search(b, max(0, start - 20), start)
93
+ if not w:
94
+ continue
95
+ word = w.group().decode("latin-1")
96
+ # trim to the longest tail that is a known prefix (e.g. "xxflag" -> "flag")
97
+ hit = next((word[k:] for k in range(len(word)) if self._ok_prefix(word[k:])), None)
98
+ if hit is not None:
99
+ self._add(hit + m.group().decode("latin-1"), chain, source)
100
+ elif not guessed and _LOOKS_LIKE.fullmatch(word + m.group().decode("latin-1")):
101
+ # unknown prefix: keep as a "maybe" (never from brute force, that's all noise)
102
+ self._add(word + m.group().decode("latin-1"), chain, source, self.maybe)
103
+ if self.custom:
104
+ for m in self.custom.finditer(b):
105
+ self._add(m.group().decode("latin-1"), chain, source)
106
+
107
+ def _add(self, flag, chain, source, into=None):
108
+ into = self.hits if into is None else into
109
+ old = into.get(flag)
110
+ if old is None or len(chain) < len(old.chain):
111
+ into[flag] = Hit(flag, list(chain), source)
112
+
113
+ def _brute(self, b, chain, source):
114
+ if not b:
115
+ return
116
+ self._match(b[::-1], chain + ["reverse"], source, True)
117
+ # caesar shifts keep the braces, so no braces means nothing to find
118
+ if b"{" in b and b"}" in b and re.search(rb"[A-Za-z]", b):
119
+ for n, table in _ROT_TABLES.items():
120
+ self._match(b.translate(table), chain + [f"rot{n}"], source, True)
121
+ self._match(b.translate(_ROT47), chain + ["rot47"], source, True)
122
+ if not self.xor or len(b) > XOR_LIMIT:
123
+ return
124
+ keys = set()
125
+ n = int.from_bytes(b, "big")
126
+ diff = (n ^ (n >> 8)).to_bytes(len(b), "big") # diff[i] = b[i] ^ b[i-1]
127
+ for sig, first in self.xor_sigs.items():
128
+ pos = diff.find(sig, 1)
129
+ while pos != -1 and len(keys) < 256:
130
+ keys.add(b[pos - 1] ^ first)
131
+ pos = diff.find(sig, pos + 1)
132
+ for k in sorted(keys):
133
+ if k:
134
+ self._match(b.translate(_XOR_TABLES[k]), chain + [f"xor(0x{k:02x})"], source, True)
135
+
136
+ # ---------- search ----------
137
+ def scan(self, data: bytes, source: str = "<input>"):
138
+ queue = _Queue()
139
+ queue.append((data, [], True, True))
140
+ seen = set()
141
+ nodes = 0 # decoded/new data: the expensive kind, limited by max_nodes
142
+ slices = 0 # plain substrings (strings/carve): cheap, much higher cap
143
+ while queue:
144
+ b, chain, is_file, fresh = queue.popleft()
145
+ key = hash(b)
146
+ if key in seen or not b:
147
+ continue
148
+ if fresh:
149
+ if nodes >= self.max_nodes:
150
+ continue
151
+ nodes += 1
152
+ else:
153
+ if slices >= 20 * self.max_nodes:
154
+ continue
155
+ slices += 1
156
+ seen.add(key)
157
+ # after a rot13/reverse step, an unknown-prefix WORD{...} is almost surely noise
158
+ self._match(b, chain, source, guessed=any(c in ("rot13", "reverse") for c in chain))
159
+ if fresh: # substrings of an already brute-forced parent were covered by it
160
+ self._brute(b, chain, source)
161
+ if len(chain) >= self.max_depth:
162
+ continue
163
+ textish = printable_ratio(b) >= 0.95
164
+ if is_file and textish and b"mov" in b.lower() and b"0x" in b.lower():
165
+ for literal in assembly_literals(b):
166
+ queue.append((literal, chain + ["join little-endian literals"], False, True))
167
+ if is_file and b.startswith(b"PK\x03\x04"):
168
+ self._unzip(b, chain, queue)
169
+ if is_file and not textish:
170
+ for name, decoded in encoded_constants(b, self.xor, self.prefix_bytes):
171
+ queue.append((decoded, chain + [name], False, True))
172
+ for s in self._strings(b):
173
+ queue.append((s, chain + ["strings"], False, False))
174
+ for s in self._utf16(b):
175
+ queue.append((s, chain + ["utf16"], False, False))
176
+ for name, fn, strict in DECODERS:
177
+ if not textish and name not in ("gzip", "zlib", "bz2", "lzma"):
178
+ continue
179
+ try:
180
+ out = fn(b)
181
+ except Exception:
182
+ out = None
183
+ if not out or out == b:
184
+ continue
185
+ sliced = any(c in ("strings", "carve") for c in chain)
186
+ r = printable_ratio(out)
187
+ compressed = name in ("gzip", "zlib", "bz2", "lzma")
188
+ # slices of a big binary give lots of accidental "valid" decodings: keep only sensible ones
189
+ if (strict and not sliced) or compressed or r >= (0.75 if strict else 0.9):
190
+ # rot13/reverse of a slice is still just a rearranged slice: the parent's brute force covered it
191
+ queue.append((out, chain + [name], compressed, fresh or name not in ("rot13", "reverse")))
192
+ if textish and len(b) > 16:
193
+ self._carve(b, chain, queue)
194
+ if self.loose:
195
+ for k, v in self.maybe.items():
196
+ self.hits.setdefault(k, v)
197
+ for k in self.hits:
198
+ self.maybe.pop(k, None)
199
+ return sorted(self.hits.values(), key=lambda h: (len(h.chain), h.flag))
200
+
201
+ def maybes(self):
202
+ return sorted(self.maybe.values(), key=lambda h: (len(h.chain), h.flag))
203
+
204
+ def _strings(self, b):
205
+ return re.findall(rb"[\x20-\x7e\t]{%d,}" % self.min_string, b)
206
+
207
+ def _utf16(self, b):
208
+ return [m.decode("utf-16le").encode()
209
+ for m in re.findall(rb"(?:[\x20-\x7e]\x00){%d,}" % self.min_string, b)]
210
+
211
+ def _carve(self, b, chain, queue):
212
+ whole = b.strip()
213
+ count = 0
214
+ for rx in CARVERS:
215
+ for m in rx.finditer(b):
216
+ tok = m.group().strip()
217
+ if tok != whole:
218
+ queue.append((tok, chain + ["carve"], False, False))
219
+ count += 1
220
+ if count >= 64:
221
+ return
222
+
223
+ def _unzip(self, b, chain, queue):
224
+ try:
225
+ with zipfile.ZipFile(io.BytesIO(b)) as z:
226
+ for info in z.infolist()[:200]:
227
+ if info.is_dir() or info.file_size > 50 * 1024 * 1024:
228
+ continue
229
+ try:
230
+ queue.append((z.read(info), chain + [f"zip:{info.filename}"], True, True))
231
+ except RuntimeError: # encrypted member
232
+ continue
233
+ except zipfile.BadZipFile:
234
+ pass
235
+
236
+
237
+ def scan_bytes(data: bytes, source: str = "<input>", **kwargs):
238
+ """Convenience wrapper: return a list of Hit for the given bytes."""
239
+ return Finder(**kwargs).scan(data, source)
@@ -0,0 +1,107 @@
1
+ """Reassemble literals and common MinGW comparison fragments by input offset."""
2
+ import base64
3
+ import binascii
4
+ import codecs
5
+ import re
6
+ import struct
7
+
8
+
9
+ def assembly_literals(data):
10
+ chunks = []
11
+ for line in data.splitlines():
12
+ match = re.match(rb"\s*mov\s+r\w+,\s*0x([0-9a-f]{8}|[0-9a-f]{16})\b", line, re.I)
13
+ if match:
14
+ chunks.append(bytes.fromhex(match[1].decode())[::-1])
15
+ elif re.match(rb"\s*(?:ret\b|\w+:)", line):
16
+ if chunks:
17
+ yield b"".join(chunks)
18
+ chunks.clear()
19
+ if chunks:
20
+ yield b"".join(chunks)
21
+
22
+
23
+ def _relative(base, match, group):
24
+ return base + match.end(group) + int.from_bytes(match[group], "little", signed=True)
25
+
26
+
27
+ def _part(code, address, read_data, read_code, xor):
28
+ literals = re.findall(rb"\xc7\x00(.{4})", code, re.S)
29
+ if literals:
30
+ result = b"".join(v.rstrip(b"\0") for v in literals)
31
+ if re.fullmatch(rb"[A-Za-z][A-Za-z0-9_]*\{", result):
32
+ return result
33
+ ref = re.search(rb"\x48\x8d[\x05\x15](.{4})", code, re.S)
34
+ if not ref:
35
+ return
36
+ data = read_data(_relative(address, ref, 1))
37
+ call_length = re.search(rb"\xba(.{4})\x48\x89\xc1\xe8(.{4})", code, re.S)
38
+ if call_length:
39
+ length = int.from_bytes(call_length[1], "little")
40
+ token = data.partition(b"\0")[0]
41
+ helper = read_code(_relative(address, call_length, 2))
42
+ if (len(token) == length and token.isalnum()
43
+ and b"\x83\xe8\x34" in helper and b"\x83\xe8\x54" in helper
44
+ and b"\x6b\xca\x1a" in helper):
45
+ return codecs.decode(token.decode("ascii"), "rot13").encode()
46
+ try:
47
+ decoded = base64.b64decode(token, validate=True)
48
+ except (ValueError, binascii.Error):
49
+ return
50
+ if len(decoded) == length:
51
+ return decoded
52
+ bound = re.search(rb"\x83\x7d\xfc(.)\x7e", code, re.S)
53
+ if not bound:
54
+ return
55
+ count = bound[1][0] + 1
56
+ key = re.search(rb"\xb8(.{4})\x89\xd1\x31\xc1", code, re.S)
57
+ if xor and key and len(data) >= count:
58
+ return bytes(v ^ key[1][0] for v in data[:count])
59
+ if b"\x01\xd2\x8d\x0c\x10" in code and len(data) >= count * 4:
60
+ values = [v - 2*i for i, (v,) in enumerate(struct.iter_unpack("<I", data[:4*count]))]
61
+ if all(32 <= v <= 126 for v in values):
62
+ return bytes(values)
63
+
64
+
65
+ _CALL = re.compile(rb"\x48\x8d\x45(.)"
66
+ rb"(?:\x48\x83\xc0(.))?\x48\x89\xc1\xe8(.{4})\x85\xc0", re.S)
67
+
68
+
69
+ def checked_fragments(sections, xor):
70
+ def read_data(address):
71
+ for name, start, section in sections:
72
+ if name != b".text" and start <= address < start + len(section):
73
+ offset = address - start
74
+ return bytes(section[offset:offset + 1024])
75
+ return b""
76
+
77
+ for name, start, section in sections:
78
+ if name != b".text":
79
+ continue
80
+ def read_code(address):
81
+ offset = address - start
82
+ if 0 <= offset < len(section):
83
+ return bytes(section[offset:offset + 256])
84
+ return b""
85
+
86
+ groups = {}
87
+ previous = -100
88
+ for call in _CALL.finditer(section):
89
+ if call.start() - previous > 64:
90
+ groups.clear()
91
+ previous = call.start()
92
+ target = _relative(start, call, 3) - start
93
+ if not 0 <= target < len(section):
94
+ continue
95
+ code = bytes(section[target:target + 256]).partition(b"\x5d\xc3")[0]
96
+ part = _part(code, start + target, read_data, read_code, xor)
97
+ if not part:
98
+ continue
99
+ pieces = groups.setdefault(call[1], {})
100
+ pieces[int.from_bytes(call[2] or b"\0", "little")] = part
101
+ ordered = bytearray()
102
+ for offset in sorted(pieces):
103
+ if offset != len(ordered):
104
+ break
105
+ ordered.extend(pieces[offset])
106
+ if re.fullmatch(rb"[A-Za-z][A-Za-z0-9_]{1,19}\{[!-~]{1,200}\}", ordered):
107
+ yield "join checked fragments by input offset", bytes(ordered)
@@ -0,0 +1,121 @@
1
+ """Carve encoded text following small, zero-padded constants in PE data."""
2
+ import base64
3
+ import re
4
+ import struct
5
+
6
+ from .fragments import checked_fragments
7
+
8
+
9
+ _TOKEN = re.compile(rb"[A-Za-z0-9+/]{8,}={0,2}")
10
+ _SHIFTED_FLAG = re.compile(rb"[A-Za-z][A-Za-z0-9_]{1,19}\{[ -~]{1,200}?\}")
11
+
12
+
13
+ def _sections(blob):
14
+ if len(blob) < 64 or blob[:2] != b"MZ":
15
+ return
16
+ offset = struct.unpack_from("<I", blob, 60)[0]
17
+ if offset + 24 > len(blob) or blob[offset:offset + 4] != b"PE\0\0":
18
+ return
19
+ count = struct.unpack_from("<H", blob, offset + 6)[0]
20
+ optional_size = struct.unpack_from("<H", blob, offset + 20)[0]
21
+ table = offset + 24 + optional_size
22
+ if count > 96 or table + count * 40 > len(blob):
23
+ return
24
+ for i in range(count):
25
+ header = table + i * 40
26
+ name = blob[header:header + 8].rstrip(b"\0")
27
+ if name not in (b".rdata", b".data", b".text"):
28
+ continue
29
+ size, start = struct.unpack_from("<II", blob, header + 16)
30
+ if start + size <= len(blob):
31
+ rva = struct.unpack_from("<I", blob, header + 12)[0]
32
+ yield name, rva, memoryview(blob)[start:start + size]
33
+
34
+
35
+ def _periodic_key(data, plain):
36
+ observed = bytes(a ^ b for a, b in zip(data, plain))
37
+ if len(observed) != len(plain):
38
+ return
39
+ for length in range(2, len(observed) - 1):
40
+ if observed[length:] == observed[:-length]:
41
+ return observed[:length]
42
+
43
+
44
+ def _xor(data, key):
45
+ return bytes(v ^ key[i % len(key)] for i, v in enumerate(data))
46
+
47
+
48
+ def _array_candidates(section, prefixes, xor):
49
+ # C strings followed by an aligned byte-shift parameter.
50
+ for token in re.finditer(rb"(?<![^\x00])([!-~]{8,512})\x00{1,8}([^\x00])\x00{3}", section):
51
+ data, shift_byte = token.groups()
52
+ shift = shift_byte[0]
53
+ shifted = bytes((v - shift) % 256 for v in data)
54
+ if _TOKEN.fullmatch(shifted):
55
+ yield f"subtract({shift})", shifted
56
+ if not xor or not re.fullmatch(rb"(?:[0-9a-fA-F]{2}){8,}", data):
57
+ continue
58
+ cipher = bytes.fromhex(data.decode())
59
+ for prefix in prefixes:
60
+ # Only complete six-bit groups are known before the flag body.
61
+ head = bytes((v + shift) % 256 for v in prefix)
62
+ known = base64.b64encode(head)[:len(head) * 8 // 6]
63
+ key = _periodic_key(cipher, known)
64
+ if key:
65
+ encoded = _xor(cipher, key)
66
+ if len(encoded) % 4 == 0 and _TOKEN.fullmatch(encoded):
67
+ plain = base64.b64decode(encoded)
68
+ result = bytes((v - shift) % 256 for v in plain)
69
+ if result.startswith(prefix) and _SHIFTED_FLAG.fullmatch(result):
70
+ yield f"hex -> xor({key.hex()}) -> base64 -> subtract({shift})", result
71
+
72
+ # Small integers stored one per little-endian 32-bit word.
73
+ for run in re.finditer(rb"(?:[\x01-\xff].\x00\x00){8,220}", section, re.S):
74
+ words = [v for v, in struct.iter_unpack("<I", run.group())]
75
+ for prefix in prefixes:
76
+ if len(prefix) < 2 or len(words) < len(prefix) or prefix[0] == prefix[1]:
77
+ continue
78
+ scale, remainder = divmod(words[0] - words[1], prefix[0] - prefix[1])
79
+ if remainder or not 1 <= scale <= 32:
80
+ continue
81
+ bias = words[0] - scale * prefix[0]
82
+ decoded = bytearray()
83
+ for word in words:
84
+ value, rem = divmod(word - bias, scale)
85
+ if rem or not 32 <= value <= 126:
86
+ break
87
+ decoded.append(value)
88
+ if decoded.startswith(prefix):
89
+ yield f"decode integer array (scale {scale}, offset {bias})", bytes(decoded)
90
+
91
+
92
+ def encoded_constants(blob, xor=True, prefixes=()):
93
+ sections = list(_sections(blob))
94
+ yield from checked_fragments(sections, xor)
95
+ for name, _, section in sections:
96
+ if name == b".text":
97
+ continue
98
+ yield from _array_candidates(section[:65536], prefixes, xor)
99
+ # A small constant can occupy a whole alignment slot before an array.
100
+ for pos in range(0, min(len(section) - 16, 64 * 1024), 16):
101
+ key = bytes(section[pos:pos + 16]).rstrip(b"\0")
102
+ if not 1 <= len(key) <= 8:
103
+ continue
104
+ payload = section[pos + 16:pos + 16 + 512]
105
+ if len(key) == 1:
106
+ shift = key[0]
107
+ decoded = bytes((v - shift) % 256 for v in payload)
108
+ token = _SHIFTED_FLAG.match(decoded)
109
+ if token:
110
+ yield f"subtract({shift})", token.group()
111
+ if xor:
112
+ for prefix in prefixes:
113
+ periodic = _periodic_key(payload, prefix)
114
+ if periodic:
115
+ token = _SHIFTED_FLAG.match(_xor(payload, periodic))
116
+ if token and token.group().startswith(prefix):
117
+ yield f"repeating xor({periodic.hex()})", token.group()
118
+ decoded = bytes(v ^ key[i % len(key)] for i, v in enumerate(payload))
119
+ token = _TOKEN.match(decoded)
120
+ if token:
121
+ yield f"xor({key.hex()})", token.group()
@@ -0,0 +1,83 @@
1
+ Metadata-Version: 2.4
2
+ Name: flag-capturer
3
+ Version: 0.1.6
4
+ Summary: Point it at a file or a string and it digs out CTF flags through layers of encoding.
5
+ Author: Alex Min
6
+ License: PolyForm-Strict-1.0.0
7
+ Project-URL: Homepage, https://github.com/icanseethejupiter/ctf_tool_kit
8
+ Keywords: ctf,flag,forensics,decoder,security
9
+ Classifier: Programming Language :: Python :: 3
10
+ Classifier: License :: Other/Proprietary License
11
+ Classifier: Environment :: Console
12
+ Classifier: Topic :: Security
13
+ Requires-Python: >=3.8
14
+ Description-Content-Type: text/markdown
15
+ License-File: LICENSE
16
+ Dynamic: license-file
17
+
18
+ # flag_capturer
19
+
20
+ Point it at a file or a string and it digs out CTF flags, peeling off layers of
21
+ encoding until something looks like `flag{...}`. Pure Python, no dependencies.
22
+
23
+ ```
24
+ $ flag_capturer challenge.bin
25
+ [+] flag{x0r_1s_n0t_encrypt10n}
26
+ challenge.bin via strings -> base64 -> xor(0x12)
27
+ ```
28
+
29
+ ## Install
30
+
31
+ ```
32
+ pip install --user git+https://github.com/icanseethejupiter/ctf_tool_kit
33
+ # no git on the machine? grab the zip instead:
34
+ pip install --user https://github.com/icanseethejupiter/ctf_tool_kit/archive/refs/heads/main.zip
35
+ ```
36
+
37
+ Then run `flag_capturer` (or the short `flagcap`). If the command is not found,
38
+ `python -m flag_capturer` always works.
39
+
40
+ ## Use
41
+
42
+ 在 Windows 资源管理器打开题目文件夹,在地址栏输入 `powershell` 并回车。运行:
43
+
44
+ ```powershell
45
+ python -m flag_capturer .
46
+ ```
47
+
48
+ 点号表示扫描当前文件夹及其子文件夹。只扫一个文件可以用 `python -m flag_capturer .\dist1.exe`。默认识别 flag、CTF 类前缀、HTB 和 THM。自定义前缀只写名字,如 `-p MYTEAM`。PowerShell 出现 `>>` 时按 Ctrl+C 回到命令行。
49
+
50
+ The static scanner recognizes several MinGW x64 comparison layouts, including checks on separate slices of the input, repeating-key XOR with a known flag prefix, and small integer arrays. It also tries little-endian literals in Intel assembly listings. A hit is a candidate recovered from file contents.
51
+
52
+ ```
53
+ flag_capturer # everything in the current folder
54
+ flag_capturer file.bin # a file
55
+ flag_capturer ./challenge_folder # every file in a folder
56
+ flag_capturer -s "ZmxhZ3toaX0=" # a string
57
+ cat dump.txt | flag_capturer # stdin
58
+ flag_capturer file -p DUCTF -p picoCTF # extra flag prefixes
59
+ flag_capturer file -r "SECRET-[0-9]{6}" # your own regex
60
+ flag_capturer file --json # for scripts
61
+ ```
62
+
63
+ ## What it tries
64
+
65
+ - printable ASCII and UTF-16 strings inside binaries
66
+ - base64 / base64url / base32 / base85 / ascii85, hex, binary, decimal, octal, URL encoding
67
+ - rot13 plus every other Caesar shift, rot47, reversed text
68
+ - single-byte XOR (all 255 keys, checked cheaply against known prefixes first)
69
+ - PE data arrays following a short, zero-padded key on a 16-byte boundary. The scanner tries repeating-key XOR on Base64 text and byte subtraction on flag-shaped text.
70
+ - gzip / zlib / bz2 / lzma streams and zip archives
71
+ - cutting base64/hex/binary-looking chunks out of longer text and trying them alone
72
+
73
+ Layers stack (default depth 5), and each hit shows the path it took.
74
+
75
+ ## Play fair
76
+
77
+ Use it on CTFs and practice boxes that allow tools. If a competition or exam says
78
+ no automated tools, leave it at home.
79
+
80
+ ## License
81
+
82
+ PolyForm Strict 1.0.0: free to install and use for noncommercial purposes,
83
+ but no redistribution and no modified versions. See `LICENSE`.
@@ -0,0 +1,13 @@
1
+ flag_capturer/__init__.py,sha256=y4TbMjZXKsdguvZKDj-vJ8qxK0C27VKxNQfivsiDs7c,214
2
+ flag_capturer/__main__.py,sha256=k1ocEWawweo1qCJWNFAAvyxz3tcY13dzvCenHszij30,48
3
+ flag_capturer/cli.py,sha256=NCZyZ9X_P5AJZzNdt1rdO3gZSouShbmZM_amawl70YU,4863
4
+ flag_capturer/decoders.py,sha256=80xHpIpFjLLItNFSk16M6x1P94_fubgSHXGy_g0LysY,4634
5
+ flag_capturer/finder.py,sha256=libin5S-TbYZZTe4coAuTrTMzoSV3D9KFNXeh6iwb9Y,10280
6
+ flag_capturer/fragments.py,sha256=TG0JcE3jCXdFFAvW5HdZcHarGCgVkUb5PpA9dRIQffw,4110
7
+ flag_capturer/pe_constants.py,sha256=4xMQyywt6GC4lP7k2bwj3klJBUh6uIRGhegEeiBrFzc,5240
8
+ flag_capturer-0.1.6.dist-info/licenses/LICENSE,sha256=PmrBdceEP3DLqc9ysndoVx3JEZYl5UDlva4i3Q42Iwk,647
9
+ flag_capturer-0.1.6.dist-info/METADATA,sha256=QgQVvGGBo8atFx3plXYSm0jhBB7Nup18ttsKIdGz9hA,3500
10
+ flag_capturer-0.1.6.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
11
+ flag_capturer-0.1.6.dist-info/entry_points.txt,sha256=G5zqNXrto8qzzeLM0p4MGAZiTgU-7KEPg5qwPLcJ2Fw,90
12
+ flag_capturer-0.1.6.dist-info/top_level.txt,sha256=TLVy1VBfZL4apI_k8f2QuljcWrRKTo6NAIJAuI8ccS0,14
13
+ flag_capturer-0.1.6.dist-info/RECORD,,
@@ -0,0 +1,5 @@
1
+ Wheel-Version: 1.0
2
+ Generator: setuptools (84.2.1)
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
5
+
@@ -0,0 +1,3 @@
1
+ [console_scripts]
2
+ flag_capturer = flag_capturer.cli:main
3
+ flagcap = flag_capturer.cli:main
@@ -0,0 +1,13 @@
1
+ PolyForm Strict License 1.0.0
2
+
3
+ Required Notice: Copyright (c) 2026 Alex Min (https://github.com/icanseethejupiter)
4
+
5
+ This software is licensed under the PolyForm Strict License 1.0.0.
6
+ Full license text: https://polyformproject.org/licenses/strict/1.0.0
7
+
8
+ In short (the full text above is what counts):
9
+ - You may download, install and run this software for noncommercial purposes
10
+ (personal use, study, hobby projects, research, education).
11
+ - You may NOT distribute it, and you may NOT make changes or new works based on it.
12
+ - Commercial use needs separate written permission from the author.
13
+ - The software is provided as is, without any warranty.
@@ -0,0 +1 @@
1
+ flag_capturer