Add check for extraneous doc files, and small doc fixes (#2852)

* change branch-if-(not)taken command category to breakpoint

* more descriptive onegadget text

* add check for extraneous files in docs/commands, move the break command's files

* remove example since it renders wrong on the web doc

and the example itself is :(

* delete extra docs with gen

.gitignore

@@ -64,7 +64,7 @@ site/
 target/
 
 npm-debug.log
-.gdb_history
+**/.gdb_history
 
 # PyCharm project files
 .idea/

docs/commands/index.md

@@ -7,6 +7,8 @@
 
 ## Breakpoint
 
+-  [break-if-not-taken](breakpoint/break-if-not-taken.md) - Breaks on a branch if it is not taken.
+-  [break-if-taken](breakpoint/break-if-taken.md) - Breaks on a branch if it is taken.
 -  [breakrva](breakpoint/breakrva.md) - Break at RVA from PIE base.
 -  [ignore](breakpoint/ignore.md) - Set ignore-count of breakpoint number N to COUNT.
 
@@ -100,7 +102,7 @@
 -  [gotplt](linux_libc_elf/gotplt.md) - Prints any symbols found in the .got.plt section if it exists.
 -  [libcinfo](linux_libc_elf/libcinfo.md) - Show libc version and link to its sources
 -  [linkmap](linux_libc_elf/linkmap.md) - Show the state of the Link Map
--  [onegadget](linux_libc_elf/onegadget.md) - Show onegadget
+-  [onegadget](linux_libc_elf/onegadget.md) - Find gadgets which single-handedly give code execution.
 -  [piebase](linux_libc_elf/piebase.md) - Calculate VA of RVA from PIE base.
 -  [plt](linux_libc_elf/plt.md) - Prints any symbols found in the .plt section if it exists.
 -  [strings](linux_libc_elf/strings.md) - Extracts and displays ASCII strings from readable memory pages of the debugged process.
@@ -135,8 +137,6 @@
 ## Misc
 
 -  [asm](misc/asm.md) - Assemble shellcode into bytes
--  [break-if-not-taken](misc/break-if-not-taken.md) - Breaks on a branch if it is not taken.
--  [break-if-taken](misc/break-if-taken.md) - Breaks on a branch if it is taken.
 -  [checksec](misc/checksec.md) - Prints out the binary security settings using `checksec`.
 -  [comm](misc/comm.md) - Put comments in assembly code.
 -  [cyclic](misc/cyclic.md) - Cyclic pattern creator/finder.

docs/commands/linux_libc_elf/onegadget.md

@@ -8,11 +8,10 @@
 ## Description
 
 
-Show onegadget
 
-Examples:
-    onegadget
-    onegadget --show-unsat
+Find gadgets which single-handedly give code execution.
+
+Uses the onegadget tool by david942j.
 
 ## Usage:
 

pwndbg/commands/branch.py

@@ -43,7 +43,7 @@ parser.add_argument(
 
 
 @pwndbg.commands.ArgparsedCommand(
-    parser, command_name="break-if-taken", category=CommandCategory.MISC
+    parser, command_name="break-if-taken", category=CommandCategory.BREAKPOINT
 )
 @pwndbg.commands.OnlyWhenRunning
 def break_if_taken(branch) -> None:
@@ -59,7 +59,7 @@ parser.add_argument(
 
 
 @pwndbg.commands.ArgparsedCommand(
-    parser, command_name="break-if-not-taken", category=CommandCategory.MISC
+    parser, command_name="break-if-not-taken", category=CommandCategory.BREAKPOINT
 )
 @pwndbg.commands.OnlyWhenRunning
 def break_if_not_taken(branch) -> None:

pwndbg/commands/onegadget.py

@@ -12,13 +12,13 @@ from pwndbg.commands import CommandCategory
 
 parser = argparse.ArgumentParser(
     formatter_class=argparse.RawTextHelpFormatter,
-    description="""Show onegadget
+    description="""
+Find gadgets which single-handedly give code execution.
 
-Examples:
-    onegadget
-    onegadget --show-unsat
+Uses the onegadget tool by david942j.
 """,
 )
+
 parser.add_argument("--show-unsat", help="Show unsatisfiable gadgets.", action="store_true")
 parser.add_argument("--no-unknown", help="Do not show unknown gadgets.", action="store_true")
 parser.add_argument("-v", "--verbose", help="Show verbose output.", action="store_true")

scripts/_gen_command_docs.py

@@ -42,6 +42,15 @@ def category_to_folder_name(category) -> str:
     assert(all(c.isalnum() or c == '_' for c in folder))
     return folder
 
+def get_files_in_dir(directory) -> list[str]:
+    file_paths = []
+    for root, dirs, files in os.walk(directory):
+        for file in files:
+            full_path = os.path.join(root, file)
+            relative_path = os.path.relpath(full_path, directory)
+            file_paths.append(relative_path)
+    return file_paths
+
 def extract_sources() -> (Dict[str, argparse.ArgumentParser], Dict[str, list[str]]):
     """
     Extract the sources.
@@ -210,6 +219,26 @@ def generate_index(filename_to_parser: Dict[str, argparse.ArgumentParser], categ
     index_autogen_warning = "<!-- THIS FILE IS AUTOGENERATED. DO NOT EDIT IT. See ~/scripts/generate_docs.sh -->\n"
     return index_autogen_warning + mdFile.get_md_text()
 
+def verify_existence(filenames: list[str]) -> (list[str], list[str]):
+    current = get_files_in_dir(base_path)
+    current = [base_path + x for x in current]
+
+    missing = [x for x in filenames if x not in current]
+    extra = [x for x in current if x not in filenames]
+
+    if missing:
+        print("Missing files:")
+        for f in missing:
+            print(f)
+        print()
+
+    if extra:
+        print("These files shouldn't exist:")
+        for f in extra:
+            print(f)
+        print()
+
+    return missing, extra
 
 def verify_files(filename_to_markdown: Dict[str, str]) -> str | None:
     """
@@ -306,7 +335,14 @@ markdowned = convert_all_to_markdown(extracted)
 markdowned[base_path + "index.md"] = generate_index(extracted, cat_to_names)
 
 if just_verify:
-    print("Verifying...")
+    print("Checking if all files are in place..")
+    missing, extra = verify_existence(markdowned.keys())
+    if missing or extra:
+        print("To fix this please run ./scripts/generate_docs.sh.")
+        exit(555)
+    print("Every file is where it should be!")
+
+    print("Verifying contents...")
     err = verify_files(markdowned)
     if err:
         print("VERIFICATION FAILED. The files differ from what would be auto-generated.")
@@ -314,8 +350,17 @@ if just_verify:
         print("Please run ./scripts/generate_docs.sh from project root and commit the changes.")
         exit(777)
 
-    print("Verification Successful.")
+    print("Verification successful!")
 else:
     print("Updating files...")
     update_files(markdowned)
     print("Update successful.")
+
+    missing, extra = verify_existence(markdowned.keys())
+    assert(not missing and "Some files are missing, which should be impossible.")
+    if extra:
+        print(f"Take care! Deleting these extra files ({len(extra)}):")
+        for e in extra:
+            print(e)
+            os.remove(e)
+        print("Deleted successfully.")