Add 4 reproducible solved examples (ps_and_qs, lost_modulus, a2s, russian_threesome) + examples README

examples/russian_threesome/s17

@@ -0,0 +1,521 @@
+   0
+  63
+   0
+  7c
+   0
+  77
+   0
+  7b
+   0
+  f2
+   0
+  6b
+   0
+  6f
+   0
+  c5
+   0
+  30
+   0
+   1
+   0
+  67
+   0
+  2b
+   0
+  fe
+   0
+  d7
+   0
+  ab
+   0
+  76
+   0
+  ca
+   0
+  82
+   0
+  c9
+   0
+  7d
+   0
+  fa
+   0
+  59
+   0
+  47
+   0
+  f0
+   0
+  ad
+   0
+  d4
+   0
+  a2
+    
+   0
+  af
+   0
+  9c
+   0
+  a4
+   0
+  72
+   0
+  c0
+   0
+  b7
+   0
+  fd
+   0
+  93
+   0
+  26
+   0
+  36
+   0
+  3f
+   0
+  f7
+   0
+  cc
+   0
+  34
+   0
+  a5
+   0
+  e5
+   0
+  f1
+   0
+  71
+   0
+  d8
+   0
+  31
+   0
+  15
+   0
+   4
+   0
+  c7
+   0
+  23
+   0
+  c3
+   0
+  18
+   0
+  96
+    
+   0
+   5
+   0
+  9a
+   0
+   7
+   0
+  12
+   0
+  80
+   0
+  e2
+   0
+  eb
+   0
+  27
+   0
+  b2
+   0
+  75
+   0
+   9
+   0
+  83
+   0
+  2c
+   0
+  1a
+   0
+  1b
+   0
+  6e
+   0
+  5a
+   0
+  a0
+   0
+  52
+   0
+  3b
+   0
+  d6
+   0
+  b3
+   0
+  29
+   0
+  e3
+   0
+  2f
+   0
+  84
+   0
+  53
+    
+   0
+  d1
+   0
+   0
+   0
+  ed
+   0
+  20
+   0
+  fc
+   0
+  b1
+   0
+  5b
+   0
+  6a
+   0
+  cb
+   0
+  be
+   0
+  39
+   0
+  4a
+   0
+  4c
+   0
+  58
+   0
+  cf
+   0
+  d0
+   0
+  ef
+   0
+  aa
+   0
+  fb
+   0
+  43
+   0
+  4d
+   0
+  33
+   0
+  85
+   0
+  45
+   0
+  f9
+   0
+   2
+   0
+  7f
+    
+   0
+  50
+   0
+  3c
+   0
+  9f
+   0
+  a8
+   0
+  51
+   0
+  a3
+   0
+  40
+   0
+  8f
+   0
+  92
+   0
+  9d
+   0
+  38
+   0
+  f5
+   0
+  bc
+   0
+  b6
+   0
+  da
+   0
+  21
+   0
+  10
+   0
+  ff
+   0
+  f3
+   0
+  d2
+   0
+  cd
+   0
+   c
+   0
+  13
+   0
+  ec
+   0
+  5f
+   0
+  97
+   0
+  44
+    
+   0
+  17
+   0
+  c4
+   0
+  a7
+   0
+  7e
+   0
+  3d
+   0
+  64
+   0
+  5d
+   0
+  19
+   0
+  73
+   0
+  60
+   0
+  81
+   0
+  4f
+   0
+  dc
+   0
+  22
+   0
+  2a
+   0
+  90
+   0
+  88
+   0
+  46
+   0
+  ee
+   0
+  b8
+   0
+  14
+   0
+  de
+   0
+  5e
+   0
+   b
+   0
+  db
+   0
+  e0
+   0
+  32
+    
+   0
+  3a
+   0
+   a
+   0
+  49
+   0
+   6
+   0
+  24
+   0
+  5c
+   0
+  c2
+   0
+  d3
+   0
+  ac
+   0
+  62
+   0
+  91
+   0
+  95
+   0
+  e4
+   0
+  79
+   0
+  e7
+   0
+  c8
+   0
+  37
+   0
+  6d
+   0
+  8d
+   0
+  d5
+   0
+  4e
+   0
+  a9
+   0
+  6c
+   0
+  56
+   0
+  f4
+   0
+  ea
+   0
+  65
+    
+   0
+  7a
+   0
+  ae
+   0
+   8
+   0
+  ba
+   0
+  78
+   0
+  25
+   0
+  2e
+   0
+  1c
+   0
+  a6
+   0
+  b4
+   0
+  c6
+   0
+  e8
+   0
+  dd
+   0
+  74
+   0
+  1f
+   0
+  4b
+   0
+  bd
+   0
+  8b
+   0
+  8a
+   0
+  70
+   0
+  3e
+   0
+  b5
+   0
+  66
+   0
+  48
+   0
+   3
+   0
+  f6
+   0
+   e
+    
+   0
+  61
+   0
+  35
+   0
+  57
+   0
+  b9
+   0
+  86
+   0
+  c1
+   0
+  1d
+   0
+  9e
+   0
+  e1
+   0
+  f8
+   0
+  98
+   0
+  11
+   0
+  69
+   0
+  d9
+   0
+  8e
+   0
+  94
+   0
+  9b
+   0
+  1e
+   0
+  87
+   0
+  e9
+   0
+  ce
+   0
+  55
+   0
+  28
+   0
+  df
+   0
+  8c
+   0
+  a1
+   0
+  89
+    
+   0
+   d
+   0
+  bf
+   0
+  e6
+   0
+  42
+   0
+  68
+   0
+  41
+   0
+  99
+   0
+  2d
+   0
+   f
+   0
+  b0
+   0
+  54
+   0
+  bb
+   0
+  16

examples/russian_threesome/s7

@@ -0,0 +1,40 @@
+4f
+70
+f4
+c3
+52
+f4
+6e
+a7
+70
+c3
+3d
+1d
+f4
+13
+f4
+c3
+e2
+1d
+41
+70
+49
+6c
+c3
+70
+f4
+3d
+ e
+c3
+3d
+41
+72
+f4
+c3
+23
+ b
+41
+70
+49
+5d
+ 7

examples/russian_threesome/solve.py

@@ -0,0 +1,49 @@
+"""
+EXAMPLE: Hack.lu 2020 — "Russian threesome" (RE, 500p, 5 solves)
+https://github.com/p4-team/ctf/tree/master/2020-10-23-hacklu/russian_threesome
+
+VULN: a balanced-ternary drum-machine dumps two permutation sectors `s7` (40
+bytes of ciphertext) and `s17` (a 256-byte S-box). The flag is recovered by
+repeatedly applying the INVERSE permutation to each `s7` byte until the sum of
+the resulting bytes equals the number of applications (a fixed-point/self-
+consistency check). Final bytes decode as CP1251 (Russian proverb).
+
+Run:
+    cd /home/code/ctfkit
+    python3 examples/russian_threesome/solve.py
+Expected flag: "Кто хочет много знать, тому мало спать."
+"""
+import os
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+
+
+def main():
+    s7 = [int(c, 16) for c in open(f"{HERE}/s7").read().split()]
+    s17 = [int(c, 16) for c in open(f"{HERE}/s17").read().split()]
+    s17 = s17[1::2]
+    inverse = [0] * 256
+    for i, j in enumerate(s17):
+        inverse[j] = i
+
+    for potential_sum in range(256 * len(s7)):
+        flag = []
+        for ch in s7:
+            c = ch
+            for _ in range(potential_sum):
+                c = inverse[c]
+            flag.append(c)
+        if sum(flag) == potential_sum:
+            b = bytes(flag)
+            try:
+                flag_str = b.decode("cp1251")
+            except Exception:
+                flag_str = b.decode("latin1")
+            print("FLAG =", flag_str)
+            return flag_str
+    print("no flag found")
+    return None
+
+
+if __name__ == "__main__":
+    main()