pdfalyzer 1.16.13__py3-none-any.whl → 1.17.0__py3-none-any.whl

pdfalyzer/helpers/rich_text_helper.py

@@ -1,17 +1,24 @@
 """
 Functions for miscellaneous Rich text/string pretty printing operations.
 """
-from typing import List, Union
+from sys import stderr
+from typing import List, Optional, Union
 
 from pypdf.generic import PdfObject
 from rich.console import Console
+from rich.panel import Panel
+from rich.padding import Padding
 from rich.text import Text
+from yaralyzer.output.rich_console import console
 
 from pdfalyzer.helpers.pdf_object_helper import pypdf_class_name
 from pdfalyzer.output.styles.node_colors import get_label_style, get_class_style_italic
 
+ARROW_BULLET = '➤ '
+
 # Usually we use the yaralyzer console but that has no highlighter
 pdfalyzer_console = Console(color_system='256')
+stderr_console = Console(color_system='256', file=stderr)
 
 
 def print_highlighted(msg: Union[str, Text], **kwargs) -> None:
@@ -32,6 +39,21 @@ def quoted_text(
     return txt
 
 
+def indented_bullet(msg: Union[str, Text], style: Optional[str] = None) -> Text:
+    return Text('  ') + bullet_text(msg, style)
+
+
+def bullet_text(msg: Union[str, Text], style: Optional[str] = None) -> Text:
+    if isinstance(msg, str):
+        msg = Text(msg, style=style)
+
+    return Text(ARROW_BULLET).append(msg)
+
+
+def mild_warning(msg: str) -> None:
+    console.print(indented_bullet(Text(msg, style='mild_warning')))
+
+
 def node_label(idnum: int, label: str, pdf_object: PdfObject, underline: bool = True) -> Text:
     """Colored text representation of a PDF node. Example: <5:FontDescriptor(Dictionary)>."""
     text = Text('<', style='white')
@@ -55,5 +77,33 @@ def number_and_pct(_number: int, total: int, digits: int = 1) -> Text:
 
 
 def pct_txt(_number: int, total: int, digits: int = 1) -> Text:
+    """Return nicely formatted percentage, e.g. '(80%)'."""
     pct = (100 * float(_number) / float(total)).__round__(digits)
     return Text(f"({pct}%)", style='blue')
+
+
+def warning_text(text: Union[str, Text]) -> Text:
+    msg = Text('').append(f"WARNING", style='bright_yellow').append(": ")
+
+    if isinstance(text, Text):
+        return msg + text
+    else:
+        return msg.append(text)
+
+
+def error_text(text: Union[str, Text]) -> Text:
+    msg = Text('').append(f"ERROR", style='bright_red').append(": ")
+
+    if isinstance(text, Text):
+        return msg + text
+    else:
+        return msg.append(text)
+
+
+def attention_getting_panel(text: Text, title: str, style: str = 'white on red') -> Padding:
+    p = Panel(text, padding=(2), title=title, style=style)
+    return Padding(p, pad=(1, 10, 2, 10))
+
+
+def print_error(text: Union[str, Text]) -> Text:
+    console.print(error_text(text))

pdfalyzer/helpers/string_helper.py

@@ -35,10 +35,15 @@ def count_pattern_matches_in_text(pattern: str, text: str) -> int:
 
 
 def count_regex_matches_in_text(regex: Pattern, text: str) -> int:
-    """For use when you precompile the regex"""
+    """For use when you precompile the regex."""
     return sum(1 for _ in regex.finditer(text))
 
 
+def exception_str(e: Exception) -> str:
+    """A string with the type and message."""
+    return f"{type(e).__name__}: {e}"
+
+
 def root_address(_string: str) -> str:
     """Strip the bracketed part off an address, e.g. '/Root[1]' => '/Root'."""
     return _string.split('[')[0]

pdfalyzer/output/character_mapping.py

@@ -19,7 +19,7 @@ CHARMAP_PADDING = (0, 2, 0, 10)
 
 
 def print_character_mapping(font: 'FontInfo') -> None:  # noqa: F821
-    """Prints the character mapping extracted by PyPDF._charmap in tidy columns"""
+    """Prints the character mapping extracted by PyPDF._charmap in tidy columns."""
     if font.character_mapping is None or len(font.character_mapping) == 0:
         log.info(f"No character map found in {font}")
         return

pdfalyzer/output/layout.py

@@ -1,6 +1,8 @@
 """
 Methods to help with the formatting of the output tables, headers, panels, etc.
 """
+from typing import List
+
 from rich import box
 from rich.padding import Padding
 from rich.panel import Panel
@@ -11,7 +13,7 @@ DEFAULT_SUBTABLE_COL_STYLES = ['white', 'bright_white']
 HEADER_PADDING = (1, 1)
 
 
-def generate_subtable(cols, header_style='subtable') -> Table:
+def generate_subtable(cols: List[str], header_style: str = 'subtable') -> Table:
     """Suited for placement in larger tables."""
     table = Table(
         box=box.SIMPLE,
@@ -33,10 +35,12 @@ def generate_subtable(cols, header_style='subtable') -> Table:
 
 
 def subheading_width() -> int:
+    """Return 75% of the console width."""
     return int(console_width() * 0.75)
 
 
 def half_width() -> int:
+    """Return 50% of the console width."""
     return int(console_width() * 0.5)
 
 
@@ -46,28 +50,34 @@ def pad_header(header: str) -> Padding:
 
 
 def print_section_header(headline: str, style: str = '') -> None:
+    """Prints a full-width section header with padding above and below."""
     console.line(2)
     _print_header_panel(headline, f"{style} reverse", True, console_width(), HEADER_PADDING)
     console.line()
 
 
 def print_section_subheader(headline: str, style: str = '') -> None:
+    """Prints a half-width section subheader with padding above."""
     console.line()
     _print_header_panel(headline, style, True, subheading_width(), HEADER_PADDING)
 
 
 def print_section_sub_subheader(headline: str, style: str = ''):
+    """Prints a half-width section sub-subheader with no padding above."""
     console.line()
     _print_header_panel(headline, style, True, half_width())
 
 
-def print_headline_panel(headline, style: str = ''):
+def print_headline_panel(headline: str, style: str = ''):
+    """Prints a full-width headline panel with no padding above or below."""
     _print_header_panel(headline, style, False, console_width())
 
 
-def print_fatal_error_panel(headline):
+def print_fatal_error_panel(headline: str):
+    """Prints a full-width red blinking panel for fatal errors."""
     print_headline_panel(headline, style='red blink')
 
 
 def _print_header_panel(headline: str, style: str, expand: bool, width: int, padding: tuple = (0,)) -> None:
+    """Helper to print a rich `Panel` with the given style, width, and padding."""
     console.print(Panel(headline, style=style, expand=expand, width=width or subheading_width(), padding=padding))

pdfalyzer/output/styles/rich_theme.py

@@ -51,7 +51,8 @@ PDFALYZER_THEME_DICT.update({
     'warn.harsh': 'reverse bright_yellow',
     # error log events
     'fail': 'bold reverse red',
-    'milderror': 'red',
+    'mild_error': 'red',  # TODO: unused?
+    'mild_warning': 'color(228) dim',
     'red_alert': 'blink bold red reverse on white',
 })
 

pdfalyzer/output/tables/decoding_stats_table.py

@@ -19,7 +19,7 @@ DECODES_SUBTABLE_COLS = ['Encoding', '#', 'Decoded', '#', 'Forced', '#', 'Failed
 
 
 def build_decoding_stats_table(scanner: BinaryScanner) -> Table:
-    """Diplay aggregate results on the decoding attempts we made on subsets of scanner.bytes"""
+    """Diplay aggregate results on the decoding attempts we made on subsets of `scanner.bytes`."""
     stats_table = _new_decoding_stats_table(scanner.label.plain if scanner.label else '')
     regexes_not_found_in_stream = []
 
@@ -58,9 +58,9 @@ def build_decoding_stats_table(scanner: BinaryScanner) -> Table:
     return stats_table
 
 
-def _new_decoding_stats_table(title) -> Table:
-    """Build an empty table for displaying decoding stats"""
-    title = prefix_with_style(title, style='blue underline')
+def _new_decoding_stats_table(title_str: str) -> Table:
+    """Build an empty table for displaying decoding stats."""
+    title = prefix_with_style(title_str, style='blue underline')
     title.append(": Decoding Attempts Summary Statistics", style='bright_white bold')
 
     table = Table(

pdfalyzer/output/tables/font_summary_table.py

@@ -15,8 +15,8 @@ ATTRIBUTES_TO_SHOW_IN_SUMMARY_TABLE = [
 ]
 
 
-def font_summary_table(font):
-    """Build a Rich Table with important info about the font"""
+def font_summary_table(font: 'FontInfo') -> Table:  # noqa: F821
+    """Build a Rich `Table` with important info about the font"""
     table = Table('', '', show_header=False)
     table.columns[0].style = 'font.property'
     table.columns[0].justify = 'right'

pdfalyzer/pdfalyzer.py

@@ -1,10 +1,5 @@
 """
-Walks the PDF objects and builds the PDF logical structure tree by
-wrapping each internal PDF object in a PdfTreeNode. Tree is managed by
-the anytree library. Information about the tree as a whole is stored
-in this class.
-Once the PDF is parsed this class manages access to
-information about or from the underlying PDF tree.
+PDFalyzer: Analyze and explore the structure of PDF files.
 """
 from os.path import basename
 from typing import Dict, Iterator, List, Optional
@@ -31,7 +26,19 @@ TRAILER_FALLBACK_ID = 10000000
 
 
 class Pdfalyzer:
+    """
+    Walks a PDF's internals and builds the PDF logical structure tree.
+
+    Each of the PDF's internal objects isw rapped in a `PdfTreeNode` object. The tree is managed
+    by the `anytree` library. Information about the tree as a whole is stored in this class.
+    Once the PDF is parsed this class provides access to info about or from the underlying PDF tree.
+    """
+
     def __init__(self, pdf_path: str):
+        """
+        Args:
+            pdf_path: Path to the PDF file to analyze
+        """
         self.pdf_path = pdf_path
         self.pdf_basename = basename(pdf_path)
         self.pdf_bytes = load_binary_data(pdf_path)
@@ -72,7 +79,7 @@ class Pdfalyzer:
         log.info(f"Walk complete.")
 
     def walk_node(self, node: PdfTreeNode) -> None:
-        """Recursively walk the PDF's tree structure starting at a given node"""
+        """Recursively walk the PDF's tree structure starting at a given node."""
         log.info(f'walk_node() called with {node}. Object dump:\n{print_with_header(node.obj, node.label)}')
         nodes_to_walk_next = [self._add_relationship_to_pdf_tree(r) for r in node.references_to_other_nodes()]
         node.all_references_processed = True
@@ -82,7 +89,7 @@ class Pdfalyzer:
                 self.walk_node(next_node)
 
     def find_node_by_idnum(self, idnum) -> Optional[PdfTreeNode]:
-        """Find node with idnum in the tree. Return None if that node is not reachable from the root."""
+        """Find node with `idnum` in the tree. Return `None` if that node is not reachable from the root."""
         nodes = [
             node for node in findall_by_attr(self.pdf_tree, name='idnum', value=idnum)
             if not isinstance(node, SymlinkNode)
@@ -96,7 +103,7 @@ class Pdfalyzer:
             raise PdfWalkError(f"Too many nodes had id {idnum}: {nodes}")
 
     def is_in_tree(self, search_for_node: PdfTreeNode) -> bool:
-        """Returns true if search_for_node is in the tree already."""
+        """Returns true if `search_for_node` is in the tree already."""
         return any([node == search_for_node for node in self.node_iterator()])
 
     def node_iterator(self) -> Iterator[PdfTreeNode]:
@@ -110,7 +117,7 @@ class Pdfalyzer:
 
     def _add_relationship_to_pdf_tree(self, relationship: PdfObjectRelationship) -> Optional[PdfTreeNode]:
         """
-        Place the relationship 'node' in the tree. Returns an optional node that should be
+        Place the `relationship` node in the tree. Returns an optional node that should be
         placed in the PDF node processing queue.
         """
         log.info(f'Assessing relationship {relationship}...')
@@ -172,7 +179,7 @@ class Pdfalyzer:
         return to_node
 
     def _resolve_indeterminate_nodes(self) -> None:
-        """Place all indeterminate nodes in the tree."""
+        """Place all indeterminate nodes in the tree. Called after all nodes have been walked."""
         indeterminate_nodes = [self.nodes_encountered[idnum] for idnum in self.indeterminate_ids]
         indeterminate_nodes_string = "\n   ".join([f"{node}" for node in indeterminate_nodes])
         log.info(f"Resolving {len(indeterminate_nodes)} indeterminate nodes: {indeterminate_nodes_string}")
@@ -185,7 +192,7 @@ class Pdfalyzer:
             IndeterminateNode(node).place_node()
 
     def _extract_font_infos(self) -> None:
-        """Extract information about fonts in the tree and place it in self.font_infos"""
+        """Extract information about fonts in the tree and place it in `self.font_infos`."""
         for node in self.node_iterator():
             if isinstance(node.obj, dict) and RESOURCES in node.obj:
                 log.debug(f"Extracting fonts from node with '{RESOURCES}' key: {node}...")
@@ -207,6 +214,6 @@ class Pdfalyzer:
         return new_node
 
     def _print_nodes_encountered(self) -> None:
-        """Debug method that displays which nodes have already been walked"""
+        """Debug method that displays which nodes have already been walked."""
         for i in sorted(self.nodes_encountered.keys()):
             console.print(f'{i}: {self.nodes_encountered[i]}')

pdfalyzer/util/argument_parser.py

@@ -7,19 +7,23 @@ from collections import namedtuple
 from functools import partial, update_wrapper
 from importlib.metadata import version
 from os import getcwd, path
+from pathlib import Path
 from typing import List, Optional
 
 from rich_argparse_plus import RichHelpFormatterPlus
 from rich.prompt import Confirm
 from rich.text import Text
+from yaralyzer.helpers.file_helper import files_in_dir
 from yaralyzer.util.argument_parser import export, parser, parse_arguments as parse_yaralyzer_args, source
 from yaralyzer.util.logging import log, log_and_print, log_argparse_result, log_current_config, log_invocation
 
-from pdfalyzer.config import ALL_STREAMS, PdfalyzerConfig
+
+from pdfalyzer.config import ALL_STREAMS, PDFALYZER, PdfalyzerConfig
 from pdfalyzer.detection.constants.binary_regexes import QUOTE_PATTERNS
 from pdfalyzer.helpers.filesystem_helper import (do_all_files_exist, extract_page_number, file_exists, is_pdf,
      with_pdf_extension)
 from pdfalyzer.helpers.rich_text_helper import print_highlighted
+from pdfalyzer.util.page_range import PageRangeArgumentValidator
 
 # NamedTuple to keep our argument selection orderly
 OutputSection = namedtuple('OutputSection', ['argument', 'method'])
@@ -124,9 +128,9 @@ parser._action_groups = parser._action_groups[:2] + [parser._action_groups[-1]]
 # Main argument parsing begins #
 ################################
 def parse_arguments():
-    """Parse command line args. Most settings are communicated to the app by setting env vars"""
+    """Parse command line args. Most args can also be communicated to the app by setting env vars."""
     if '--version' in sys.argv:
-        print(f"pdfalyzer {version('pdfalyzer')}")
+        print(f"pdfalyzer {version(PDFALYZER)}")
         sys.exit()
 
     args = parser.parse_args()
@@ -158,10 +162,16 @@ def parse_arguments():
     return args
 
 
-def output_sections(args, pdfalyzer) -> List[OutputSection]:
+def output_sections(args: Namespace, pdfalyzer: 'Pdfalyzer') -> List[OutputSection]:  # noqa: F821
     """
     Determine which of the tree visualizations, font scans, etc should be run.
     If nothing is specified output ALL sections other than --streams which is v. slow/verbose.
+
+    Args:
+        args: parsed command line arguments
+        pdfalyzer: the `pdfalyzer` instance whose methods will be called to produce output
+    Returns:
+        List[OutputSection]: List of `OutputSection` namedtuples with 'argument' and 'method' fields
     """
     # Create a partial for print_font_info() because it's the only one that can take an argument
     # partials have no __name__ so update_wrapper() propagates the 'print_font_info' as this partial's name
@@ -196,9 +206,10 @@ def all_sections_chosen(args):
     return len([s for s in ALL_SECTIONS if vars(args)[s]]) == len(ALL_SECTIONS)
 
 
-###############################################
-# Separate arg parser for combine_pdfs script #
-###############################################
+#############################################################
+#  Separate arg parsers for combine_pdfs and other scripts  #
+#############################################################
+
 MAX_QUALITY = 10
 
 combine_pdfs_parser = ArgumentParser(
@@ -251,6 +262,90 @@ def parse_combine_pdfs_args() -> Namespace:
     return args
 
 
+###########################################
+# Parse args for extract_pdf_pages() #
+###########################################
+page_range_validator = PageRangeArgumentValidator()
+
+extract_pdf_parser = ArgumentParser(
+    formatter_class=RichHelpFormatterPlus,
+    description="Extract pages from one PDF into a new PDF.",
+)
+
+extract_pdf_parser.add_argument('pdf_file', metavar='PDF_FILE', help='PDF to extract pages from')
+
+extract_pdf_parser.add_argument('--page-range', '-r',
+                                type=page_range_validator,
+                                help=page_range_validator.HELP_MSG,
+                                required=True)
+
+extract_pdf_parser.add_argument('--destination-dir', '-d',
+                                help="directory to write the new PDF to",
+                                default=Path.cwd())
+
+extract_pdf_parser.add_argument('--debug', action='store_true', help='turn on debug level logging')
+
+
+def parse_pdf_page_extraction_args() -> Namespace:
+    args = extract_pdf_parser.parse_args()
+
+    if not is_pdf(args.pdf_file):
+        log.error(f"'{args.pdf_file}' is not a PDF.")
+        sys.exit(-1)
+    elif not Path(args.destination_dir).exists():
+        log.error(f"Destination dir '{args.destination_dir}' does not exist.")
+        sys.exit(1)
+
+    return args
+
+
+############################################
+# Parse args for extract_text_from_pdfs() #
+############################################
+extract_text_parser = ArgumentParser(
+    formatter_class=RichHelpFormatterPlus,
+    description="Extract the text from one or more files or directories.",
+    epilog="If any of the FILE_OR_DIRs is a directory all files in that directory will be extracted."
+)
+
+extract_text_parser.add_argument('file_or_dir', nargs='+', metavar='FILE_OR_DIR')
+extract_text_parser.add_argument('--debug', action='store_true', help='turn on debug level logging')
+
+extract_text_parser.add_argument('--page-range', '-r',
+                                 type=page_range_validator,
+                                 help=f"[PDFs only] {page_range_validator.HELP_MSG}")
+
+extract_text_parser.add_argument('--print-as-parsed', '-p',
+                                 action='store_true',
+                                 help='print pages as they are parsed instead of waiting until document is fully parsed')
+
+
+def parse_text_extraction_args() -> Namespace:
+    args = extract_text_parser.parse_args()
+    args.files_to_process = []
+
+    for file_or_dir in args.file_or_dir:
+        file_path = Path(file_or_dir)
+
+        if not file_path.exists():
+            log.error(f"File '{file_path}' doesn't exist!")
+            sys.exit(-1)
+        elif file_path.is_dir():
+            args.files_to_process.extend(files_in_dir(file_path, 'pdf'))
+        else:
+            args.files_to_process.append(file_path)
+
+    if args.page_range and (len(args.files_to_process) > 1 or not is_pdf(args.files_to_process[0])):
+        log.error(f"--page-range can only be specified for a single PDF")
+        sys.exit(-1)
+
+    return args
+
+
+#############
+#  Helpers  #
+#############
+
 def ask_to_proceed() -> None:
     """Exit if user doesn't confirm they want to proceed."""
     if not Confirm.ask(Text("Proceed anyway?")):

pdfalyzer/util/page_range.py

@@ -0,0 +1,54 @@
+"""
+A range of page numbers. Copied from clown_sort repo.
+"""
+import re
+from argparse import ArgumentTypeError
+from dataclasses import dataclass
+from typing import Tuple
+
+PAGE_RANGE_REGEX = re.compile('\\d(-\\d)?')
+
+
+@dataclass
+class PageRange:
+    page_range: str
+
+    def __post_init__(self):
+        if not PAGE_RANGE_REGEX.match(self.page_range):
+            raise ValueError(f"Invalid page range '{self.page_range}'")
+
+        if '-' in self.page_range:
+            (self.first_page, self.last_page) = (int(p) for p in self.page_range.split('-'))
+        else:
+            self.first_page = int(self.page_range)
+            self.last_page = self.first_page + 1
+
+        if self.last_page <= self.first_page:
+            raise ValueError(f"Invalid page range {self.__repr__()}")
+
+    def in_range(self, page_number) -> bool:
+        """Returns `True` if `page_number` is in this range."""
+        return page_number >= self.first_page and page_number < self.last_page
+
+    def file_suffix(self) -> str:
+        """String that can be used as file suffix."""
+        if self.first_page + 1 == self.last_page:
+            return f"page_{self.first_page}"
+        else:
+            return f"pages_{self.first_page}-{self.last_page}"
+
+    def to_tuple(self) -> Tuple[int, int]:
+        return (self.first_page, self.last_page)
+
+    def __repr__(self) -> str:
+        return f"PageRange({self.first_page}, {self.last_page})"
+
+
+class PageRangeArgumentValidator(object):
+    HELP_MSG = "a single digit ('11') or a range ('11-15') (WILL NOT extract the last page)"
+
+    def __call__(self, value):
+        if not PAGE_RANGE_REGEX.match(value):
+            raise ArgumentTypeError("Argument has to match '{}'".format(PAGE_RANGE_REGEX.pattern))
+
+        return PageRange(value)

{pdfalyzer-1.16.13.dist-info → pdfalyzer-1.17.0.dist-info}/METADATA

@@ -1,13 +1,13 @@
 Metadata-Version: 2.1
 Name: pdfalyzer
-Version: 1.16.13
+Version: 1.17.0
 Summary: PDF analysis tool. Scan a PDF with YARA rules, visualize its inner tree-like data structure in living color (lots of colors), force decodes of suspicious font binaries, and more.
 Home-page: https://github.com/michelcrypt4d4mus/pdfalyzer
 License: GPL-3.0-or-later
 Keywords: ascii art,binary,color,cybersecurity,DFIR,encoding,font,infosec,maldoc,malicious pdf,malware,malware analysis,pdf,pdfs,pdf analysis,pypdf,threat assessment,threat hunting,threat intelligence,threat research,threatintel,visualization,yara
 Author: Michel de Cryptadamus
 Author-email: michel@cryptadamus.com
-Requires-Python: >=3.9.2,<4.0
+Requires-Python: >=3.10,<4.0
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Environment :: Console
 Classifier: Intended Audience :: Information Technology
@@ -18,24 +18,26 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
-Classifier: Programming Language :: Python :: 3.9
 Classifier: Topic :: Artistic Software
 Classifier: Topic :: Scientific/Engineering :: Visualization
 Classifier: Topic :: Security
+Provides-Extra: extract
+Requires-Dist: PyMuPDF (>=1.26.4,<2.0.0) ; extra == "extract"
 Requires-Dist: anytree (>=2.13,<3.0)
 Requires-Dist: pypdf (>=6.0.0,<7.0.0)
-Requires-Dist: yaralyzer (>=1.0.7,<2.0.0)
+Requires-Dist: pytesseract (>=0.3.13,<0.4.0) ; extra == "extract"
+Requires-Dist: yaralyzer (>=1.0.9,<2.0.0)
 Project-URL: Changelog, https://github.com/michelcrypt4d4mus/pdfalyzer/blob/master/CHANGELOG.md
 Project-URL: Documentation, https://github.com/michelcrypt4d4mus/pdfalyzer
 Project-URL: Repository, https://github.com/michelcrypt4d4mus/pdfalyzer
 Description-Content-Type: text/markdown
 
-<!-- ![Tests](https://img.shields.io/github/workflow/status/michelcrypt4d4mus/pdfalyzer/tests?label=tests)  -->
-![Python Version](https://img.shields.io/pypi/pyversions/pdfalyzer)
 [![GithubRelease](https://img.shields.io/github/v/release/michelcrypt4d4mus/pdfalyzer?sort=semver)](https://pypi.org/project/pdfalyzer/)
-[![GitHub last commit](https://img.shields.io/github/last-commit/michelcrypt4d4mus/pdfalyzer)](https://github.com/michelcrypt4d4mus/pdfalyzer)
 ![PyPiRelease](https://img.shields.io/pypi/v/pdfalyzer)
+[![GitHub last commit](https://img.shields.io/github/last-commit/michelcrypt4d4mus/pdfalyzer)](https://github.com/michelcrypt4d4mus/pdfalyzer)
+![Python Version](https://img.shields.io/pypi/pyversions/pdfalyzer)
 ![Downloads](https://img.shields.io/pypi/dm/pdfalyzer)
+[![Tests](https://github.com/michelcrypt4d4mus/pdfalyzer/actions/workflows/python-package.yml/badge.svg)](https://github.com/michelcrypt4d4mus/pdfalyzer/actions/workflows/python-package.yml)
 
 
 # THE PDFALYZER
@@ -114,7 +116,12 @@ If you provide none of the flags in the `ANALYSIS SELECTION` section of the `--h
 The `--streams` output is the one used to hunt for patterns in the embedded bytes and can be _extremely_ verbose depending on the `--quote-char` options chosen (or not chosen) and contents of the PDF. [The Yaralyzer](https://github.com/michelcrypt4d4mus/yaralyzer) handles this task; if you want to hunt for patterns in the bytes other than bytes surrounded by backticks/frontslashes/brackets/quotes/etc. you may want to use The Yaralyzer directly. As The Yaralyzer is a prequisite for The Pdfalyzer you may already have the `yaralyze` command installed and available.
 
 ### Setting Command Line Options Permanently With A `.pdfalyzer` File
-When you run `pdfalyze` on some PDF the tool will check for a file called `.pdfalyzer` first in the current directory and then in the home directory. If it finds a file in either such place it will load configuration options from it. Documentation on the options that can be configured with these files lives in [`.pdfalyzer.example`](.pdfalyzer.example) which doubles as an example file you can copy into place and edit to your needs. Handy if you find yourself typing the same command line options over and over again.
+When you run `pdfalyze` on some PDF the tool will check for a file called `.pdfalyzer` in these places in this order:
+
+1. the current directory
+2. the user's home directory
+
+If it finds a `.pdfalyzer` file in either such place it will load configuration options from it. Documentation on the options that can be configured with these files lives in [`.pdfalyzer.example`](.pdfalyzer.example) which doubles as an example file you can copy into place and edit to your needs. Handy if you find yourself typing the same command line options over and over again.
 
 ### Environment Variables
 Even if you don't configure your own `.pdfalyzer` file you may still glean some insight from reading the descriptions of the various variables in [`.pdfalyzer.example`](.pdfalyzer.example); there's a little more exposition there than in the output of `pdfalyze -h`.
@@ -125,10 +132,9 @@ Run `pdfalyzer_show_color_theme` to see the color theme employed.
 ### Guarantees
 Warnings will be printed if any PDF object ID between 1 and the `/Size` reported by the PDF itself could not be successfully placed in the tree. If you do not get any warnings then all[^2] of the inner PDF objects should be seen in the output.
 
-## Example Usage
+## Example Malicious PDF Investigation
 [BUFFERZONE Team](https://bufferzonesecurity.com) posted [an excellent example](https://bufferzonesecurity.com/the-beginners-guide-to-adobe-pdf-malware-reverse-engineering-part-1/) of how one might use The Pdfalyzer in tandem with [Didier Stevens' PDF tools](#installing-didier-stevenss-pdf-analysis-tools) to investigate a potentially malicious PDF (archived in [the `doc/` dir in this repo](./doc/) if the link rots).
 
--------------
 
 ## Use As A Code Library
 For info about setting up a dev environment see [Contributing](#contributing) below.
@@ -239,9 +245,27 @@ Things like, say, a hidden binary `/F` (PDF instruction meaning "URL") followed
 
 -------------
 
+
 # PDF Resources
 ## Included PDF Tools
-The Pdfalyzer ships with a command line tool `combine_pdfs` that combines multiple PDFs into a single PDF. Run `combine_pdfs --help` to see the options.
+The Pdfalyzer comes with a few command line tools:
+
+#### `combine_pdfs`
+Combines multiple PDFs into a single PDF. Run `combine_pdfs --help` to see the options.
+
+#### `extract_pdf_pages`
+Extracts page ranges (e.g. "10-25") from a PDF and writes them to a new PDF. Run `extract_pdf_pages --help` to see the options.
+![](doc/extract_pages_from_pdf_help.png)
+
+#### `extract_text_from_pdfs`
+Extracts text from a PDF, including applying OCR to all embedded images. Requires that you install The Pdfalyzer's optional dependencies:
+
+```bash
+pipx install pdfalyzer[extract]
+```
+
+Run `extract_text_from_pdfs --help` to see the options.
+
 
 ## 3rd Party PDF Tools
 ### Installing Didier Stevens's PDF Analysis Tools