From b898cb992ca1aacbfeb76eff4559791d0dc3ddbb Mon Sep 17 00:00:00 2001 From: Raul Date: Mon, 16 Mar 2026 01:09:31 +0200 Subject: [PATCH] #414 Fixed documentation and further added details about the newest model in GView --- .github/workflows/gh-pages.yml | 4 +- docs/requirements.txt | 4 +- docs/source/_templates/.gitkeep | 0 docs/source/architecture.rst | 70 ++++++++++++- docs/source/character_table.rst | 5 + docs/source/conf.py | 6 +- docs/source/configuration.rst | 8 +- docs/source/contributing.rst | 36 ++++++- docs/source/core.rst | 32 +++--- docs/source/description.rst | 39 ++++++- docs/source/development.rst | 22 ++-- docs/source/education.rst | 124 ++++++++++++++++++++++ docs/source/global_plugins.rst | 19 +++- docs/source/hashes.rst | 5 + docs/source/index.rst | 17 +-- docs/source/macho.rst | 84 +++------------ docs/source/plugin_development.rst | 162 +++++++++++++++++++++++++++++ docs/source/prefetch.rst | 16 +-- docs/source/security.rst | 35 +++++++ docs/source/specific_plugins.rst | 23 ++-- docs/source/usage.rst | 65 +++++++++++- 21 files changed, 639 insertions(+), 137 deletions(-) create mode 100644 docs/source/_templates/.gitkeep create mode 100644 docs/source/education.rst create mode 100644 docs/source/plugin_development.rst create mode 100644 docs/source/security.rst diff --git a/.github/workflows/gh-pages.yml b/.github/workflows/gh-pages.yml index 5798e1bf..dbe2c158 100644 --- a/.github/workflows/gh-pages.yml +++ b/.github/workflows/gh-pages.yml @@ -11,8 +11,8 @@ jobs: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v1 - # Standard drop-in approach that should work for most people. + - uses: actions/checkout@v4 + # Build Sphinx docs from docs/ and publish to gh-pages. - uses: ammaraskar/sphinx-action@master with: docs-folder: "docs/" diff --git a/docs/requirements.txt b/docs/requirements.txt index cbf1e365..a04ad654 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,2 +1,2 @@ -sphinx -sphinx-rtd-theme +sphinx>=5.0,<8 +sphinx-rtd-theme>=1.2,<3 diff --git a/docs/source/_templates/.gitkeep b/docs/source/_templates/.gitkeep new file mode 100644 index 00000000..e69de29b diff --git a/docs/source/architecture.rst b/docs/source/architecture.rst index 552991f7..35bc0584 100644 --- a/docs/source/architecture.rst +++ b/docs/source/architecture.rst @@ -1,2 +1,70 @@ GView architecture -=================== \ No newline at end of file +================== + +Architecture flow +----------------- + +1. **Content type** — Determine whether the content is binary or textual. For text, + detect encoding and decode to a standardized format (e.g. UTF-16). + +2. **Plugin selection** — Search available data identifier (Type) plugins for one that + can interpret the data. If none matches, fall back to a generic plugin that only + distinguishes binary vs. text. + +3. **Viewers and extraction** — The chosen Type plugin selects suitable smart viewers. + Users can switch viewers and use them to extract artifacts or data from the content. + +4. **Iteration** — Repeat steps 1–3 for extracted components, using artifacts from + previous steps to drive further analysis. + +Directory structure +------------------- + +:: + + GView/ + ├── AppCUI/ # UI framework (subproject, separate repo) + ├── GViewCore/ # Core library + │ ├── include/ + │ │ └── GView.hpp # Public API for plugins + │ └── src/ + │ ├── include/Internal.hpp + │ ├── App/ # Application logic, dialogs + │ ├── View/ # Smart viewers (Buffer, Text, Lexical, Image, Grid, Dissasm, Container) + │ ├── Utils/ # DataCache, ZonesList, ErrorList, etc. + │ ├── Hashes/ # Hash implementations + │ ├── Decoding/ # Base64, ZLIB, etc. + │ ├── DigitalSignature/ + │ ├── Dissasembly/ # Capstone wrapper + │ ├── Security/ # Restricted mode, crypto + │ └── Type/ # Plugin loading and type matching + ├── GView/ # Main executable + ├── Types/ # Type plugins (PE, ELF, MACHO, PDF, PCAP, ZIP, CSV, etc.) + ├── GenericPlugins/ # Generic plugins (Hashes, EntropyVisualizer, Dropper, SyncCompare, Unpacker, etc.) + ├── cmake/ + ├── docs/ + └── build/ / bin/ + +Code structure +-------------- + +* **GViewCore** — Core library: application logic, smart viewers, hashes, decoding, + digital signatures, disassembly, plugin loading. Plugins use only ``GView.hpp``. +* **GView** — Main executable. +* **Types/** — Type-specific plugins (PE, ELF, Mach-O, PDF, PCAP, ZIP, CSV, INI, JS, etc.). +* **GenericPlugins/** — Generic plugins (Hashes, EntropyVisualizer, Dropper, SyncCompare, + Unpacker, CharacterTable, FileDownloader). +* **AppCUI** — Terminal UI framework (subproject). + +Diagrams +-------- + +High-level architecture: + +.. image:: _static/GView.svg + :alt: GView high-level architecture + +Core (GViewCore) architecture: + +.. image:: _static/GViewCore.svg + :alt: GViewCore architecture diff --git a/docs/source/character_table.rst b/docs/source/character_table.rst index e69de29b..691c5ff5 100644 --- a/docs/source/character_table.rst +++ b/docs/source/character_table.rst @@ -0,0 +1,5 @@ +Character table +=============== + +Generic plugin for viewing and inspecting character tables and code pages. +Details to be added. diff --git a/docs/source/conf.py b/docs/source/conf.py index 881aca67..70db22a7 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -72,7 +72,7 @@ # # This is also used if you do content translation via gettext catalogs. # Usually you set "language" from the command line for these cases. -language = None +language = 'en' # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. @@ -198,4 +198,6 @@ # Example configuration for intersphinx: refer to the Python standard library. -intersphinx_mapping = {'https://docs.python.org/': None} +intersphinx_mapping = { + 'python': ('https://docs.python.org/3/', None), +} diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst index 703019d7..858512f5 100644 --- a/docs/source/configuration.rst +++ b/docs/source/configuration.rst @@ -5,7 +5,7 @@ GView is configured via ``GView.ini`` file (that should be located next to GView The following section should be seen in a ``GView.ini`` file: -* ``[GView]`` - a section with the general configuration for GView. Tipically it contains associated key for changing the view, cache size, etc. +* ``[GView]`` - a section with the general configuration for GView. Typically it contains associated key for changing the view, cache size, etc. * ``[AppCUI]`` - a section with the general configuration for AppCUI framework (color, frontend, etc) * ``[Type.]`` - various sections that describe characteristics of each supported type in GView * ``[View.]`` - various section for each smart view @@ -13,7 +13,7 @@ The following section should be seen in a ``GView.ini`` file: Types ----- -A ``[Type.xxx]``` section usually contains the following: +A ``[Type.xxx]`` section usually contains the following: * a `Description` field that explains the type of the plugin * a `Extension` field that can be a simple string or a list of strings containing the list of extensions associated with this field. @@ -37,7 +37,7 @@ A ``[Type.xxx]``` section usually contains the following: | Rule | Type | Usage | Example | +==================+=========+==================================================+================================+ | magic | Binary | Identifies a binary magic from the start of the | **magic**:FF 20 30 | -| | Files | file. A magic must be foollowed by a list of hex | | +| | Files | file. A magic must be followed by a list of hex | | | | | values separated with spaces | | +------------------+---------+--------------------------------------------------+--------------------------------+ | startswith | Text | Checks if a file starts with a specific text | **startswith**:#include | @@ -57,6 +57,6 @@ A ``[Type.xxx]``` section usually contains the following: .. code-block:: ini - Pattern = ["startswith:ABC","linestartswith:test"] ; identifies a text file where either the firs line starts with `ABC` + Pattern = ["startswith:ABC","linestartswith:test"] ; identifies a text file where either the first line starts with `ABC` ; or there is a line within the first 10 lines that starts with `test` diff --git a/docs/source/contributing.rst b/docs/source/contributing.rst index 1851ec2e..59b64c0a 100644 --- a/docs/source/contributing.rst +++ b/docs/source/contributing.rst @@ -1,2 +1,36 @@ GView contributing -=================== \ No newline at end of file +================== + +Start contributing +------------------ + +1. **Clone with submodules**:: + + git clone --recurse-submodules /GView.git + +2. **Build** — Use CMake and vcpkg as described in :doc:`usage`. Enable tests with + ``-DENABLE_TESTS=ON``. + +3. **Documentation** — Sphinx sources are under ``docs/``. Install tooling:: + + pip install -r docs/requirements.txt + + Build HTML docs:: + + cd docs && make html + + Output is in ``docs/build/html``. + +4. **Code style** — Follow the project's C++20 conventions: ``PascalCase`` for types + and functions, ``camelCase`` for variables. Use only the public API in + ``GViewCore/include/GView.hpp`` for plugin development. See :doc:`plugin_development` + for the plugin contract, patterns, and conventions. + +5. **Pull requests** — Open PRs against ``main``. CI runs on push and on pull requests; + ensure builds and tests pass. + +Reporting issues +---------------- + +Use the repository issue tracker for bugs and feature requests. Check existing issues +and use the provided templates when possible. diff --git a/docs/source/core.rst b/docs/source/core.rst index 80d7cc6c..a51708c9 100644 --- a/docs/source/core.rst +++ b/docs/source/core.rst @@ -1,20 +1,22 @@ GView Core -=================== +========== Core ------------------ +---- -// TODO: +This section covers internal and format-specific details used by GViewCore and +various Type plugins. Content is expanded over time. -Golang ------------------ -https://go.dev/src/runtime/symtab.go -https://go.dev/src/runtime/runtime2.go -https://github.com/0xjiayu/go_parser/blob/master/pclntbl.py -https://github.com/strazzere/golang_loader_assist/blob/master/golang_loader_assist.py#L200 -https://www.freebuf.com/articles/others-articles/176803.html -https://gist.github.com/matteobertozzi/1521947 -https://docs.google.com/document/d/1lyPIbmsYbXnpNj57a261hgOYVpNRcgydurVQIyZOz_o/pub -https://github.com/dutchcoders/jupyter-radare2/blob/master/Annotating%20Go%20Binaries%20using%20Cutter.ipynb -https://go.dev/src/debug/gosym/pclntab.go -https://www.mandiant.com/resources/golang-internals-symbol-recovery \ No newline at end of file +Golang binary support (references) +------------------------------------ + +Type plugins (e.g. PE, ELF, Mach-O) use the following references for Go symbol and +runtime parsing: + +* `Go runtime symtab `__ +* `Go runtime2 `__ +* `gosym/pclntab `__ +* `go_parser pclntbl `__ +* `golang_loader_assist `__ +* `Mandiant: Golang internals - symbol recovery `__ +* `Go binaries in Cutter `__ \ No newline at end of file diff --git a/docs/source/description.rst b/docs/source/description.rst index f72ad4f3..30d1d6bb 100644 --- a/docs/source/description.rst +++ b/docs/source/description.rst @@ -1,2 +1,39 @@ GView description -=================== \ No newline at end of file +================= + +General description +------------------- + +**GView** is a powerful tool for examining files or any data with a defined structure, +such as buffers or memory zones. Users can leverage the diverse range of available +visualization options to effectively analyze and interpret the information. + +From a developer perspective, GView offers a flexible platform to create plugins that +parse various data structures. Developers can create customized views and enhance +analysis capabilities by writing Type plugins (for specific file formats) or Generic +plugins (for operations that apply to any file). + +Use cases +--------- + +* Malware analysis and incident response +* File format reverse engineering +* Network traffic analysis (PCAP) +* Binary executable analysis (PE, ELF, Mach-O) +* Document forensics (PDF, DOC, EML) +* Archive inspection (ZIP, ISO) + +See GView in action +------------------- + +**Scenario 1: Malicious infection** +A screencast shows how GView can analyze the contents of a compromised system. By +examining network traffic, security analysts can uncover how malicious actors gained +unauthorized access. GView's visualization helps identify suspicious hints and +understand the attack's impact. (`Open video `__) + +**Scenario 2: Suspicious email** +GView is used to analyze the impact of a breach after a victim has been infected. +The cause was a suspicious email. By analyzing email headers, attachments, and +embedded content, analysts can uncover hidden malicious code or phishing attempts. +(`Open video `__) diff --git a/docs/source/development.rst b/docs/source/development.rst index b549b0bd..97547b4e 100644 --- a/docs/source/development.rst +++ b/docs/source/development.rst @@ -1,10 +1,20 @@ GView development -=================== +================= -Github workflows ------------------ +Testing +------- -Github workflows will be automatically triggered on push to ``main`` and on ``pull_request``. +* Tests are enabled with ``-DENABLE_TESTS=ON`` at configure time. +* Unit tests are in files matching ``**/tests_*.cpp``. +* The testing build produces a ``GViewTesting`` executable instead of ``GView``. +* The ``run_core_tests()`` macro from ``cmake/core_testing.cmake`` is used to + register test sources. -If any workflows need to be triggered for other branches, one could create a draft PR to start testing or manually trigger the workflows from the `Actions` page, while selecting the required workflow. -The contributor will be greeted with a ``This workflow has a workflow_dispatch event trigger`` and a ``Run workflow`` button. \ No newline at end of file +Run the test executable from your build directory after building with tests enabled. + +GitHub workflows +---------------- + +Workflows run on push to ``main`` and on ``pull_request``. To run them for other +branches, create a draft PR or trigger manually from the Actions page: choose the +workflow and use **Run workflow** when it has a ``workflow_dispatch`` trigger. \ No newline at end of file diff --git a/docs/source/education.rst b/docs/source/education.rst new file mode 100644 index 00000000..0c55e870 --- /dev/null +++ b/docs/source/education.rst @@ -0,0 +1,124 @@ +GView use in education +====================== + +This page describes how GView can be used in educational settings for learning and +evaluation, including the Learning and Evaluation Mode (built on :doc:`security`), +the typical workflow, and security considerations. + +Use case +-------- + +Step-by-step workflow +~~~~~~~~~~~~~~~~~~~~~ + +**Step 1: Launch GView and connect to the course server.** + +The student launches GView and selects the Learning and Evaluation Mode from the +menu options. Then the student connects securely to the course server using a +unique login token. Each student is assigned a unique token used to identify them. +If the server accepts the connection, it returns the policy in JSON format. + +**Step 2: Load and apply the policy in GView.** + +After the policy is received, it is automatically loaded in GView: features that +are disabled by the policy become unusable (e.g., save, copy, export), and plugins +that are disabled become unavailable. From this point on, the student works in a +controlled environment that allows a fair evaluation of their skills. The features +needed for the student to perform the analysis remain accessible, so their +workflow is not impacted. + +**Step 3: Request a task.** + +The student can now request problems to work on. GView uses the student's token and +sends a secure request to the server for a specific task (or for the next available +task, depending on the policy). + +If the server accepts the request, it streams back binary content to GView along +with the task requirements. Typically this is binary executable files (e.g., PE +files). That content is opened inside GView either as a buffer (from memory only) or +from a file (depending on the policy), enabling the student to start their analysis. + +**Step 4: Perform the analysis.** + +The student follows the usual process used in laboratories. First, the student +inspects the raw bytes from a binary perspective using the Buffer Viewer. This +helps get a bigger picture and understand the global structure and the kind of data +involved. + +If working with an executable file, the student then analyzes the content using the +Disassembly Viewer to observe the disassembled code. The student can follow jump and +call instructions to see control flow and destinations. To keep track of +information, they can add comments to the code. + +In an example scenario, the requirement might be to identify the value of the third +variable from the stack. Upon inspection, the student can determine that the +correct value is 3. + +**Step 5: Submit the solution.** + +The student submits the solution directly from GView: + +* If the solution is wrong, the server returns a failure response, and the student + can try again. +* If the solution is correct, the server returns a success response and the number + of points assigned for that task. + +This immediate feedback lets students receive grading instantly, without waiting for +human evaluation and intervention. + +**Step 6: Send telemetry.** + +At the end of the task, telemetry data is securely sent to the server. It is used +for course improvement only. No invasive data is collected. In this use case, the +focus is on the following metrics: + +* time to solve; +* number of attempts; +* feature usage of GView. + +Why this use case is important in education +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +One main advantage of this approach is that it supports both learning and +evaluation in the same way. During labs, students learn to use GView and its +features (e.g., following jumps, annotating code) and gain confidence. Because the +same process is used for evaluation, when the evaluation starts we can measure +reverse engineering skills rather than tool setup skills. + +Telemetry is useful from a teaching perspective. We monitor whether features are +used and how often. If some features are not used, this can mean one of three +things: + +1. The feature was not properly explained. +2. The student is not yet familiar with it. +3. The student prefers not to use it (e.g., personal preference). + +This information helps improve the entire course. Depending on how students behave +in certain situations, we can see which topics need clearer explanations, which +tasks are confusing, or which GView features need better integration in the +learning workflow. We also track whether the tool reaches invalid states (e.g., +crashes). In this way, we can better understand where students struggle and where +support is needed, even when that is not explicitly communicated to the teachers. + +Security and limitations +------------------------- + +The Learning and Evaluation Mode is designed to reduce the risk of leakage, improve +fairness, and make cheating harder during evaluation, but it cannot achieve that +perfectly. + +The mode provides a secure way to send tasks and receive metrics and responses over +a secured network connection. Leaking binaries is harder when they are kept in +secured memory only (not on disk). This is reinforced by disabling copy, save, and +export. On Windows, the screen is protected from screenshots. + +However, students can still bypass these protections: for example, by taking a +photo of the screen with a phone, typing the content manually into another +application, patching GView (since it is open source), or using an external tool. + +We treat the Learning and Evaluation Mode as a best-effort protection that +substantially raises the effort required to cheat, rather than as a perfect +solution. In an educational environment, students might be tempted to copy +binaries to use other tools or to share them. The goal is to reduce easy access +without making the tool so restrictive that students fight the tool instead of +working with it. diff --git a/docs/source/global_plugins.rst b/docs/source/global_plugins.rst index 240b6cf9..2a3ff492 100644 --- a/docs/source/global_plugins.rst +++ b/docs/source/global_plugins.rst @@ -1,12 +1,21 @@ GView Global Plugins -=================== +==================== -Global Plugins ------------------ +Generic plugins work with any file type and are registered via INI configuration. +They provide dialogs or operations that apply universally, such as: + +* **Hashes** — Compute MD5, SHA, CRC and other hashes over selection or file +* **Entropy** — Entropy analysis and visualization +* **Dropper** — Extract artifacts from buffers +* **Sync Compare** — File comparison +* **Unpacker** — Decompression utilities + +These plugins are configured in ``GView.ini`` under ``[Generic.*]`` sections. +See :doc:`configuration` for the configuration file format. .. toctree:: - :maxdepth: 2 - :caption: Contents: + :maxdepth: 1 + :caption: Reference character_table hashes \ No newline at end of file diff --git a/docs/source/hashes.rst b/docs/source/hashes.rst index e69de29b..44deed0f 100644 --- a/docs/source/hashes.rst +++ b/docs/source/hashes.rst @@ -0,0 +1,5 @@ +Hashes +====== + +Generic plugin for computing hashes (MD5, SHA-1, SHA-256, CRC, etc.) over the +current selection or the entire file. Details to be added. diff --git a/docs/source/index.rst b/docs/source/index.rst index 3a792416..47fddb00 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,26 +1,29 @@ -.. GView documentation master file, created by - sphinx-quickstart on Wed Jun 8 22:21:07 2022. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. +.. GView documentation master file. Welcome to GView's documentation! ================================= +**GView** is a cross-platform reverse engineering and data analysis framework. +It lets you examine files, buffers, or memory through multiple visualization options +and a plugin-based architecture for file formats and generic operations. + .. toctree:: :maxdepth: 2 - :caption: Contents: + :caption: Contents description usage + education architecture + configuration + security + plugin_development core global_plugins specific_plugins development contributing - - Indices and tables ================== diff --git a/docs/source/macho.rst b/docs/source/macho.rst index 7bd6f06b..443db5c5 100644 --- a/docs/source/macho.rst +++ b/docs/source/macho.rst @@ -1,71 +1,17 @@ -GView Specific Plugin Mach-O -=================== +GView Specific Plugin: Mach-O +============================= -Mach-O ------------------ +The Mach-O plugin parses Mach-O and Mach-O Fat binaries (macOS/iOS), including Go +binaries, with section/segment/symbol extraction and code signature validation. -https://opensource.apple.com/source/llvmCore/llvmCore-3425.0.36/tools/llvm-objdump/MachODump.cpp.auto.html -https://stackoverflow.com/questions/54134172/where-is-the-source-code-of-llvm-otool-mac -https://cdmana.com/2022/01/202201291147523264.html -http://xelz.info/blog/2019/01/11/ios-code-signature -https://opensource.apple.com/source/Security/Security-59754.80.3/SecurityTool/sharedTool/codesign.c.auto.html -https://opensource.apple.com/source/Security -https://github.com/apple-opensource/Security/search?l=C&p=6&q=CFDataCreate -https://github.com/apple-opensource/Security/blob/a070b704ca4d37793326cdc9be14fe157fde602b/OSX/libsecurity_codesigning/lib/CSCommonPriv.h -https://github.com/apple-opensource/Security/blob/a070b704ca4d37793326cdc9be14fe157fde602b/codesign_wrapper/check_entitlements.c -https://github.com/apple-opensource/Security/blob/a070b704ca4d37793326cdc9be14fe157fde602b/SecurityTool/sharedTool/codesign.c -https://github.com/apple-opensource/Security/blob/a070b704ca4d37793326cdc9be14fe157fde602b/OSX/libsecurity_utilities/lib/blob.h -https://github.com/opensource-apple/cctools/blob/fdb4825f303fd5c0751be524babd32958181b3ed/Makefile -https://github.com/opensource-apple/cctools/blob/master/otool/ofile_print.c -http://newosxbook.com/tools/jtool.html -https://llvm.org/doxygen/BinaryFormat_2MachO_8h_source.html -https://reviews.llvm.org/rGaaf00f3f19c1be69ce10d53236f824c2580c2139 -https://cdmana.com/2022/01/202201291147523264.html -https://gist.github.com/laanwj/a0e00bcd3fe4cd2aa1c0803e91310495#file-validate_macho_sig-py -https://macholib.readthedocs.io/en/latest -https://github.com/ronaldoussoren/macholib/tree/master/macholib -https://opensource.apple.com/source/Security/Security-59754.80.3/OSX/libsecurity_codesigning/lib -https://opensource.apple.com/source/Security/Security-59754.80.3/codesign_wrapper -https://opensource.apple.com/source/Security/Security-59754.80.3/CMS -https://stackoverflow.com/questions/29598313/checking-code-integrity-in-ios -https://github.com/toriningen/apple-security-framework/blob/master/OSX/libsecurity_codesigning/lib/codedirectory.cpp -https://qa.1r1g.com/sf/ask/2071881941 -https://opensource.apple.com/source/Security/Security-57740.1.18/OSX/libsecurity_codesigning/lib/codedirectory.cpp.auto.html -https://blacktop.github.io/ipsw/docs/commands/macho/#macho-info---fileset-entry -https://github.com/blacktop/ipsw/blob/412077d8da1420277938a047d397fbaaee098193/pkg/dyld/closure.go -https://github.com/blacktop/go-macho/blob/master/export.go -https://redmaple.tech/blogs/macho-files -https://github.com/zhlynn/zsign/blob/44f15cae53e4a5a000fa7486dd72f472a4c75ee4/openssl.cpp#L11 -https://github.com/CM4all/libcommon/blob/2b7a8fbdd653d23ce44300d1298e560200aedc50/src/lib/openssl/LoadFile.cxx -https://github.com/zhlynn/zsign/blob/master/signing.cpp -https://github.com/zhlynn/zsign -https://llvm.org/doxygen/BinaryFormat_2MachO_8h_source.html -https://llvm.org/doxygen/namespacellvm_1_1MachO.html#a16655d8dcb288f8b3bdc27c0ed3bdc69 -https://www.nextop.de/NeXTstep_3.3_Developer_Documentation/DevTools/14_MachO/MachO.htmld/index.html -https://github.com/kazzmir/decompiler/blob/master/disassembler/mach/usr/include/mach-o/nlist.h -https://github.com/aidansteele/osx-abi-macho-file-format-reference/blob/master/README.md -https://github.com/llvm/llvm-project/blob/ce2ae381246df89e560c0dfd0a7fdf275f266d9e/lld/MachO/SymbolTable.cpp -https://github.com/llvm/llvm-project/blob/ce2ae381246df89e560c0dfd0a7fdf275f266d9e/lld/MachO/InputFiles.cpp -https://github.com/hdoc/llvm-project/blob/release/13.x/llvm/include/llvm/BinaryFormat/MachO.h#L1401 -https://opensource.apple.com/source/xnu/xnu-2050.18.24/EXTERNAL_HEADERS/mach-o/stab.h -https://github.com/frnext/MacDependency/blob/f9a9a3b9f60c0e1a7a0d8850bfe5697a38703ade/MachO/symboltableentry.cpp -https://github.com/lief-project/LIEF/blob/77328b0071c7254567d9e8383ea0f5f876f9da17/src/MachO/Symbol.cpp -https://github.com/search?l=C%2B%2B&q=%22N_PEXT%22&type=Code -https://opensource.apple.com/source/xnu/xnu-4570.71.2/EXTERNAL_HEADERS/mach-o/nlist.h -https://opensource.apple.com/source/xnu/xnu-201/EXTERNAL_HEADERS/mach-o/nlist.h.auto.html -https://llvm.org/doxygen/BinaryFormat_2MachO_8h_source.html -https://opensource.apple.com/source/dyld/dyld-45.1/src/ImageLoader.cpp.auto.html -https://opensource.apple.com/source/dyld/dyld-852.2/src/ImageLoaderMachO.cpp.auto.html -https://opensource.apple.com/source/dyld/dyld-43/src/ImageLoaderMachO.cpp.auto.html -https://opensource.apple.com/source/dyld/dyld-239.3/src/ImageLoaderMachO.cpp -https://github.com/llvm/llvm-project/blob/93d1a623cecb6f732db7900baf230a13e6ac6c6a/llvm/test/ObjectYAML/MachO/dylib_dylinker_command.yaml -https://opensource.apple.com/source/dyld/dyld-852.2 -https://oscourse-tsinghua.gitbook.io/ucore-analysis/ucore/kern/debug/stab_h -https://android.googlesource.com/platform/external/lcc/+/f401a679882f0a0dc05b91ab8f507a09305803d4/src/stab.h -https://github.com/llvm/llvm-project/blob/bbaeb1ee0ee03ffd5161f1414c8b36d7d7fcdbb7/llvm/include/llvm/BinaryFormat/MachO.h -https://github.com/Tenloy/tenloy.github.io/blob/5ac4c70b91c80723b3e20560830d083fd8ae1dfb/source/_posts/2021-09-23-(%E4%BA%8C)%20Mach-O%20%E6%96%87%E4%BB%B6%E7%BB%93%E6%9E%84.md -https://reviews.llvm.org/D34668 -https://redmaple.tech/blogs/macho-files -http://www.newosxbook.com/articles/CodeSigning.pdf -https://opensource.apple.com/source/libsecurity_codesigning/libsecurity_codesigning-55032/lib/codedirectory.h.auto.html -https://opensource.apple.com/source/dyld/dyld-655.1.1/dyld3/MachOLoaded.cpp.auto.html \ No newline at end of file +References +---------- + +* **LLVM / Mach-O format**: `MachODump `__, `BinaryFormat/MachO.h `__, `MachO namespace `__, `SymbolTable.cpp `__ +* **Apple Security / codesign**: `Security `__, `codesign.c `__, `codedirectory.h `__ +* **cctools / otool**: `ofile_print.c `__ +* **dyld**: `ImageLoaderMachO `__, `dyld `__, `MachOLoaded `__ +* **XNU headers**: `mach-o/nlist.h `__, `mach-o/stab.h `__ +* **Third-party**: `macholib `__, `go-macho (blacktop) `__, `LIEF MachO `__, `zsign `__, `osx-abi-macho-file-format-reference `__ +* **Articles**: `Code Signing (newosxbook) `__, `Mach-O (redmaple) `__, `iOS code signature `__ +* **Validation**: `validate_macho_sig.py `__ diff --git a/docs/source/plugin_development.rst b/docs/source/plugin_development.rst new file mode 100644 index 00000000..ca33ea18 --- /dev/null +++ b/docs/source/plugin_development.rst @@ -0,0 +1,162 @@ +Plugin development +================== + +This page is for developers who want to add new file format support (Type plugins) or +extend GView. Use the public API only; internal APIs are not stable for plugins. + +Public vs internal API +---------------------- + +* **GView.hpp** (``GViewCore/include/GView.hpp``) — Public API. All types, interfaces, + and utilities for plugins live here. Plugins must rely only on this header. + +* **Internal.hpp** (``GViewCore/src/include/Internal.hpp``) — Private implementation. + Used only inside GViewCore. Do not use in Type or Generic plugins. + +Type plugin contract +-------------------- + +Every Type plugin must export these C functions (``extern "C"``): + +* **Validate** — Return whether a buffer matches this file type (magic, extension, etc.). +* **CreateInstance** — Return a new instance of your TypeInterface implementation. +* **PopulateWindow** — Configure viewers and panels for the opened file. +* **UpdateSettings** — Register patterns, priority, and commands in the INI layer. + +Your plugin class must inherit ``GView::TypeInterface`` and implement: + +* **GetTypeName()** — Plugin display name. +* **RunCommand(string_view)** — Handle custom commands (e.g. from menus). +* **UpdateKeys(KeyboardControlsInterface*)** — Register keyboard shortcuts. +* **GetSmartAssistantContext(...)** — Provide context for the smart assistant (can return minimal JSON). + +Smart viewers +------------- + +Each Type plugin chooses which viewers to create in ``PopulateWindow``. Available +viewers and their settings classes: + +* **BufferViewer** — Hex/binary with zones, colors, bookmarks. Settings: + ``GView::View::BufferViewer::Settings`` +* **TextViewer** — Plain text with line wrapping. Settings: + ``GView::View::TextViewer::Settings`` +* **LexicalViewer** — Syntax-highlighted code with folding. Settings: + ``GView::View::LexicalViewer::Settings`` +* **ImageViewer** — Image display. Settings: ``GView::View::ImageViewer::Settings`` +* **GridViewer** — Tabular data (CSV, etc.). Settings: + ``GView::View::GridViewer::Settings`` +* **DissasmViewer** — Disassembly (Capstone) with type annotations. Settings: + ``GView::View::DissasmViewer::Settings`` +* **ContainerViewer** — Tree view for archives / container content. Settings: + ``GView::View::ContainerViewer::Settings`` + +Key interfaces +-------------- + +**Object** — The opened file, buffer, or process. From ``TypeInterface`` you get +``obj`` (pointer to Object). Use ``obj->GetData()`` for a ``DataCache&`` and +``obj->GetName()`` / ``obj->GetPath()`` for identification. + +**DataCache** — Cached access to file/buffer data. Use ``Get(offset, size, failIfCannotRead)`` +for a ``BufferView``, ``CopyToBuffer(...)`` for a copy, and ``Copy(offset, object)`` to +read a struct. ``GetSize()`` gives the total size. + +**WindowInterface** — In ``PopulateWindow`` you receive a ``Reference``. +Call ``GetObject()`` to get the Object, ``CreateViewer(settings)`` for each viewer, +and ``AddPanel(Pointer(...), vertical)`` for custom panels. + +Adding a new Type plugin +------------------------- + +1. Create a directory under ``Types/YOUR_PLUGIN/`` (e.g. ``Types/MyFormat/``). +2. Add ``include/your_plugin.hpp`` with your TypeInterface implementation. +3. Add ``src/your_plugin.cpp`` (and optional panels) with the exported functions + (Validate, CreateInstance, PopulateWindow, UpdateSettings). +4. Add a ``CMakeLists.txt`` (copy from an existing Type such as ``Types/PREFETCH``). +5. In the repository root ``CMakeLists.txt``, add ``add_subdirectory(Types/YOUR_PLUGIN)``. + +Coding conventions +------------------ + +* **C++20** — Required (set in CMake). +* **Naming** — PascalCase for types and functions, camelCase for variables. +* **Strings** — Prefer ``std::string_view``; use ``FixSizeString`` or + ``LocalString`` for fixed/stack buffers. +* **Pointers** — Use ``Reference`` (non-owning) and ``Pointer`` (owning) from + AppCUI; avoid raw ``new``/``delete``. +* **Errors** — Use ``CHECK(condition, returnValue, "message")`` for validation; + ``GView::Utils::ErrorList`` for multiple errors; ``GView::Utils::GStatus`` when + returning a status message. +* **Data access** — Use ``DataCache`` and ``BufferView``; avoid unnecessary copies. + +Common patterns +--------------- + +Creating viewers in PopulateWindow +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Get your type from the window, configure the settings (zones, callbacks), then create +the viewer and add panels:: + + PLUGIN_EXPORT bool PopulateWindow(Reference win) { + auto myType = win->GetObject()->GetContentType(); + + BufferViewer::Settings settings; + settings.AddZone(0, sizeof(Header), ColorPair{Color::White, Color::DarkBlue}, "Header"); + settings.SetPositionToColorCallback(myType.ToBase()); + win->CreateViewer(settings); + + win->AddPanel(Pointer(new MyPanel(myType, win)), true); + return true; + } + +Reading file data +~~~~~~~~~~~~~~~~~ + +Use ``Object::GetData()`` to get a ``DataCache&``. Use ``Copy`` for structs and +``Get()`` for variable-length data:: + + bool MyTypeFile::Update() { + auto& data = obj->GetData(); + if (!data.Copy(0, header)) return false; + auto buf = data.Get(offset, size, true); + if (!buf.IsValid()) return false; + return true; + } + +PositionToColorInterface (buffer highlighting) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Implement this interface so the buffer viewer can color ranges by offset:: + + bool MyTypeFile::GetColorForBuffer(uint64 offset, BufferView buf, BufferColor& result) { + if (offset >= section.start && offset < section.end) { + result.start = section.start; + result.end = section.end; + result.color = ColorPair{Color::Yellow, Color::DarkRed}; + return true; + } + result.Reset(); + return false; + } + + +Generic plugins +--------------- + +Generic plugins work with any file type and are registered via ``GView.ini`` +(see :doc:`configuration`). They usually provide dialogs or operations (e.g. hashes, +entropy, comparison). Implement them under ``GenericPlugins/`` and register in INI; +they do not implement the Type plugin contract above. + +Quick reference +--------------- + +* **Add new file format** — ``Types/NEW_TYPE/`` — TypeInterface, Validate, PopulateWindow +* **Add generic operation** — ``GenericPlugins/`` — Window-based dialogs +* **Add hash algorithm** — ``GViewCore/src/Hashes/`` — Hash classes in GView.hpp +* **Add decoding** — ``GViewCore/src/Decoding/`` — Decoding namespace +* **Modify viewer behavior** — ``GViewCore/src/View/`` — ViewControl, Settings +* **Add keyboard shortcut** — TypeInterface — UpdateKeys(), KeyboardControl +* **Add panel to Type** — ``Types/*/src/Panel*.cpp`` — TabPage, ListView +* **AI assistant context** — TypeInterface — GetSmartAssistantContext() diff --git a/docs/source/prefetch.rst b/docs/source/prefetch.rst index 548ed386..6453cde4 100644 --- a/docs/source/prefetch.rst +++ b/docs/source/prefetch.rst @@ -1,8 +1,12 @@ -Global Plugins Prefetch -=================== +GView Specific Plugin: Prefetch +=============================== -Prefetch ------------------ +The Prefetch plugin parses Windows Prefetch (``.pf``) files, extracting paths, +volumes, and dependencies in an organized view. MAM (compressed Prefetch) is +also supported via the MAM plugin. -https://github.com/libyal/libfwsi/blob/main/documentation/Windows%20Shell%20Item%20format.asciidoc -https://github.com/MathildeVenault/SysMainView \ No newline at end of file +References +---------- + +* `Windows Shell Item format (libyal/libfwsi) `__ +* `SysMainView `__ \ No newline at end of file diff --git a/docs/source/security.rst b/docs/source/security.rst new file mode 100644 index 00000000..db41ad2c --- /dev/null +++ b/docs/source/security.rst @@ -0,0 +1,35 @@ +Security and restricted mode +============================= + +GView provides a **Restricted Mode** (exposed in the UI as Learning and Evaluation +Mode) for exam and assessment scenarios where you need to limit features, enforce +time windows, and reduce leakage of sensitive content (e.g. task binaries). + +Public API (GView.hpp) +---------------------- + +The following are in ``GView::Security::RestrictedMode``: + +* **Policy** — Configuration: id, purpose, time window (startsAt/endsAt), disabled + features, allowed plugins list, watermark text, screen protection option, content key id. +* **Feature** — Enum of features that can be disabled: Copy, Export, SaveAs, Plugins, + LLMHints, Clipboard, Screenshots. +* **LoadPolicyFromFiles(jsonPath, signaturePath, publicKey, outPolicy)** — Load and + verify an Ed25519-signed policy JSON. Returns ``GStatus``; on success, ``outPolicy`` + is filled. +* **IsActive()** — Returns whether restricted mode is currently active. +* **GetCurrentPolicy()** — Returns the current policy (read-only) or nullptr. + +When restricted mode is active, disabled features are unavailable in the UI (e.g. save, +copy, export), and only plugins listed in the policy are allowed. This supports fair +evaluation and reduces easy copying of task content. See :doc:`education` for the +typical workflow (connect to server, load policy, request task, submit solution, +telemetry). + +Limitations +----------- + +Restricted mode is best-effort. It does not prevent all leakage (e.g. photographing +the screen, typing content elsewhere, or patching the open-source binary). It is +designed to raise the effort required to cheat and to keep task data off disk when +using memory-only buffers. diff --git a/docs/source/specific_plugins.rst b/docs/source/specific_plugins.rst index a676b455..d82ef9db 100644 --- a/docs/source/specific_plugins.rst +++ b/docs/source/specific_plugins.rst @@ -1,22 +1,15 @@ -GView Specific Plugins -=================== +GView Specific Plugins (Type Plugins) +===================================== -Specific Plugins ------------------ +Type plugins parse specific file formats and provide smart viewers and panels. +The following pages describe selected plugins and their references: .. toctree:: :maxdepth: 2 - :caption: Contents: + :caption: Documented plugins macho - mzpe - elf - lnk - bmp - ico - job prefetch - mam - iso - pcap - csv \ No newline at end of file + +Other supported types include PE, ELF, BMP, ICO, LNK, JOB, MAM, ISO, PCAP, CSV, PDF, ZIP, and more. +See the main README for a full table of data identifier plugins. \ No newline at end of file diff --git a/docs/source/usage.rst b/docs/source/usage.rst index 0a751b8d..7f3b047c 100644 --- a/docs/source/usage.rst +++ b/docs/source/usage.rst @@ -1,2 +1,65 @@ GView usage -=================== \ No newline at end of file +=========== + +First run +--------- + +Pre-built archives are produced by the CI/CD pipeline for each supported operating +system. Download the archive for your platform and run the main binary (``GView`` or +``GView.exe`` on Windows). + +Windows +~~~~~~~ +Unzip the release archive and run ``GView.exe`` (tested on Windows 10 x64). + +Linux +~~~~~ +Builds are made on Ubuntu 20.04 (Intel). Precompiled binaries run on Ubuntu 20.04 and +Ubuntu 22.04. Older images (e.g. Ubuntu 18.04) may have incompatible GLIBC. + +macOS / OS X +~~~~~~~~~~~~ +You may see a warning that macOS cannot verify the app. Until binaries are digitally +signed and notarized, you must manually allow each binary to run in System Preferences +→ Security & Privacy. Do not disable Gatekeeper system-wide. + +Building from source +-------------------- + +* **CMake** is used to build the project on all platforms. +* **vcpkg** is used for dependencies; see the repository `.github/workflows/ci.yml` + for the build pipeline. + +Clone with submodules:: + + git clone --recurse-submodules /GView.git + +Configure and build: + +**Windows (Visual Studio):** + + cmake -B build -S . -DCMAKE_BUILD_TYPE=Release + cmake --build build --config Release + +**Linux / macOS:** + + cmake -B build -S . -DCMAKE_BUILD_TYPE=Release + cmake --build build + +**With tests:** add ``-DENABLE_TESTS=ON``. The build produces a ``GViewTesting`` +executable; unit tests live in ``**/tests_*.cpp`` and are driven by +``cmake/core_testing.cmake``. + +Configuration +------------- + +GView is configured via ``GView.ini`` next to the executable. If the file is missing, +run ``GView reset`` from the CLI to create a default one. See :doc:`configuration` +for the INI format and options. + +Dependencies +------------ + +Dependencies are managed via vcpkg (``vcpkg.json``). Main third-party libraries: +AppCUI (terminal UI, subproject), Capstone (disassembly), OpenSSL (crypto), SQLite3, +zlib, PCRE2, LLVMDemangle (symbol demangling).