Add CramFS implementation (#1)

Author: Horofic

.gitattributes

@@ -0,0 +1 @@
+tests/_data/** filter=lfs diff=lfs merge=lfs -text

.github/pull_request_template.md

@@ -0,0 +1,22 @@
+<!--
+Thank you for submitting a Pull Request. Please:
+* Read our commit style guide:
+    Commit messages should adhere to the following points:
+    * Separate subject from body with a blank line
+    * Limit the subject line to 50 characters as much as possible
+    * Capitalize the subject line
+    * Do not end the subject line with a period
+    * Use the imperative mood in the subject line
+    * The verb should represent what was accomplished (Create, Add, Fix etc)
+    * Wrap the body at 72 characters
+    * Use the body to explain the what and why vs. the how
+  For an example, look at the following link:
+  https://docs.dissect.tools/en/latest/contributing/style-guide.html#example-commit-message
+* Include a description of the proposed changes and how to test them.
+* After creation, associate the PR with an issue, under the development section.
+  Or use closing keywords in the body during creation:
+  E.G:
+  * close(|s|d) #<nr>
+  * fix(|es|ed) #<nr>
+  * resolve(|s|d) #<nr>
+-->

.github/workflows/dissect-ci.yml

@@ -0,0 +1,37 @@
+name: Dissect CI
+on:
+  push:
+    branches:
+      - main
+    tags:
+      - '*'
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  ci:
+    uses: fox-it/dissect-workflow-templates/.github/workflows/dissect-ci-template.yml@main
+    secrets: inherit
+
+  publish:
+    if: ${{ github.ref_name == 'main' || github.ref_type == 'tag' }}
+    needs: [ci]
+    runs-on: ubuntu-latest
+    environment: dissect_publish
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: packages
+          path: dist/
+      # According to the documentation, it automatically looks inside the `dist/` folder for packages.
+      - name: Publish package distributions to Pypi
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  trigger-tests:
+    needs: [publish]
+    uses: fox-it/dissect-workflow-templates/.github/workflows/dissect-ci-demand-test-template.yml@main
+    secrets: inherit
+    with:
+      on-demand-test: 'dissect.target'

.gitignore

@@ -0,0 +1,11 @@
+coverage.xml
+.coverage
+dist/
+.eggs/
+*.egg-info/
+*.pyc
+__pycache__/
+.pytest_cache/
+tests/_docs/api
+tests/_docs/build
+.tox/

COPYRIGHT

@@ -0,0 +1,5 @@
+Dissect is released as open source by Fox-IT (https://www.fox-it.com) part of NCC Group Plc (https://www.nccgroup.com)
+
+Developed by the Dissect Team (dissect@fox-it.com) and made available at https://github.com/fox-it/dissect.target
+
+License terms: AGPL3 (https://www.gnu.org/licenses/agpl-3.0.html)

LICENSE

@@ -0,0 +1,4 @@
+exclude .gitattributes
+exclude .gitignore
+recursive-exclude .github/ *
+recursive-exclude tests/_data/ *

MANIFEST.in

@@ -1,2 +1,53 @@
 # dissect.cramfs
-A Dissect module implementing a parser for the Cram file system, commonly used in appliance or device firmware.
+
+A Dissect module implementing a parser for the compressed ROM/RAM file system (or cramfs), commonly used in appliance or device firmware. For more
+information, please see [the documentation](https://docs.dissect.tools/en/latest/projects/dissect.cramfs/index.html).
+
+## Requirements
+
+This project is part of the Dissect framework and requires Python.
+
+Information on the supported Python versions can be found in the Getting Started section of [the documentation](https://docs.dissect.tools/en/latest/index.html#getting-started).
+
+## Installation
+
+`dissect.cramfs` is available on [PyPI](https://pypi.org/project/dissect.cramfs/).
+
+```bash
+pip install dissect.cramfs
+```
+
+## Build and test instructions
+
+This project uses `tox` to build source and wheel distributions. Run the following command from the root folder to build
+these:
+
+```bash
+tox -e build
+```
+
+The build artifacts can be found in the `dist/` directory.
+
+`tox` is also used to run linting and unit tests in a self-contained environment. To run both linting and unit tests
+using the default installed Python version, run:
+
+```bash
+tox
+```
+
+For a more elaborate explanation on how to build and test the project, please see [the
+documentation](https://docs.dissect.tools/en/latest/contributing/tooling.html).
+
+## Contributing
+
+The Dissect project encourages any contribution to the codebase. To make your contribution fit into the project, please
+refer to [the development guide](https://docs.dissect.tools/en/latest/contributing/developing.html).
+
+## Copyright and license
+
+Dissect is released as open source by Fox-IT (<https://www.fox-it.com>) part of NCC Group Plc
+(<https://www.nccgroup.com>).
+
+Developed by the Dissect Team (<dissect@fox-it.com>) and made available at <https://github.com/fox-it/dissect>.
+
+License terms: AGPL3 (<https://www.gnu.org/licenses/agpl-3.0.html>). For more information, see the LICENSE file.

README.md

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+from dissect.cramfs.cramfs import BlockStream, CramFS, INode
+from dissect.cramfs.exception import (
+    Error,
+    FileNotFoundError,
+    NotADirectoryError,
+    NotAFileError,
+    NotASymlinkError,
+)
+
+__all__ = [
+    "BlockStream",
+    "CramFS",
+    "Error",
+    "FileNotFoundError",
+    "INode",
+    "NotADirectoryError",
+    "NotAFileError",
+    "NotASymlinkError",
+]

dissect/cramfs/__init__.py

@@ -0,0 +1,103 @@
+# References:
+# - https://github.com/digiampietro/lzma-uncramfs/blob/master/cramfs_fs.h
+# - https://github.com/npitre/cramfs-tools/blob/master/linux/cramfs_fs.h
+
+from __future__ import annotations
+
+from dissect.cstruct import cstruct
+
+cramfs_def = """
+#define CRAMFS_MAGIC                    0x28cd3d45	/* some random number */
+#define CRAMFS_SIGNATURE                b"Compressed ROMFS"
+#define CRAMFS_BLOCK_SIZE               4096
+
+/*
+ * Width of various bitfields in struct cramfs_inode.
+ * Primarily used to generate warnings in mkcramfs.
+ */
+#define CRAMFS_MODE_WIDTH               16
+#define CRAMFS_UID_WIDTH                16
+#define CRAMFS_GID_WIDTH                8
+#define CRAMFS_NAMELEN_WIDTH            6
+#define CRAMFS_OFFSET_WIDTH             26
+
+/*
+ * Since inode.namelen is a unsigned 6-bit number, the maximum cramfs
+ * path length is 63 << 2 = 252.
+ */
+#define CRAMFS_MAXPATHLEN               (((1 << CRAMFS_NAMELEN_WIDTH) - 1) << 2)
+#define CRAMFS_SIZE_WIDTH               24
+
+struct cramfs_inode {
+    uint32 mode:16;
+    uint32 uid:16;
+
+    /* SIZE for device files is i_rdev */
+    uint32 size:24;
+    uint32 gid:8;
+
+    /* NAMELEN is the length of the file name, divided by 4 and rounded up.  (cramfs doesn't support hard links.) */
+    /* OFFSET: For symlinks and non-empty regular files, this
+        contains the offset (divided by 4) of the file data in
+        compressed form (starting with an array of block pointers;
+        see README).  For non-empty directories it is the offset
+        (divided by 4) of the inode of the first file in that
+        directory.  For anything else, offset is zero. */
+    uint32 namelen:6;
+    uint32 offset:26;
+    char name[namelen * 4];
+};
+
+struct cramfs_info {
+    uint32 crc;
+    uint32 edition;
+    uint32 blocks;
+    uint32 files;
+};
+
+/*
+ * Superblock information at the beginning of the FS.
+ */
+struct cramfs_super_block {
+    uint32 magic;           /* 0x28cd3d45 - random number */
+    uint32 size;            /* length in bytes */
+    uint32 flags;           /* feature flags */
+    uint32 future;          /* reserved for future use */
+    char signature[16];     /* "Compressed ROMFS" */
+    cramfs_info fsid;       /* unique filesystem info */
+    char name[16];          /* user-defined name */
+    cramfs_inode root;      /* root inode data */
+};
+
+/*
+ * Feature flags
+ *
+ * 0x00000000 - 0x000000ff: features that work for all past kernels
+ * 0x00000100 - 0xffffffff: features that don't work for past kernels
+ */
+#define CRAMFS_FLAG_FSID_VERSION_2      0x00000001  /* fsid version #2 */
+#define CRAMFS_FLAG_SORTED_DIRS         0x00000002  /* sorted dirs */
+#define CRAMFS_FLAG_HOLES               0x00000100  /* support for holes */
+#define CRAMFS_FLAG_WRONG_SIGNATURE     0x00000200  /* reserved */
+#define CRAMFS_FLAG_SHIFTED_ROOT_OFFSET 0x00000400  /* shifted root fs */
+#define CRAMFS_FLAG_BLKSZ_MASK          0x00003800  /* block size mask */
+#define CRAMFS_FLAG_COMP_METHOD_MASK    0x0000C000  /* Compression method mask */
+#define CRAMFS_FLAG_EXT_BLOCK_POINTERS  0x00000800  /* block pointer extensions */
+#define CRAMFS_FLAG_DIRECT_POINTER      0x40000000  /* direct pointers flag */
+#define CRAMFS_FLAG_UNCOMPRESSED_BLOCK  0x80000000  /* uncompressed block flag */
+
+#define CRAMFS_FLAG_BLKSZ_SHIFT         11
+#define CRAMFS_FLAG_COMP_METHOD_SHIFT   14
+#define CRAMFS_FLAG_COMP_METHOD_NONE    0
+#define CRAMFS_FLAG_COMP_METHOD_GZIP    1
+#define CRAMFS_FLAG_COMP_METHOD_LZMA    2
+
+/*
+ * Valid values in super.flags.  Currently we refuse to mount
+ * if (flags & ~CRAMFS_SUPPORTED_FLAGS).  Maybe that should be
+ * changed to test super.future instead.
+ */
+#define CRAMFS_SUPPORTED_FLAGS	        (0x000000ff | CRAMFS_FLAG_HOLES | CRAMFS_FLAG_WRONG_SIGNATURE | CRAMFS_FLAG_SHIFTED_ROOT_OFFSET | CRAMFS_FLAG_BLKSZ_MASK | CRAMFS_FLAG_COMP_METHOD_MASK)
+"""  # noqa: E501
+
+c_cramfs = cstruct().load(cramfs_def)