binarycookies 2.2.3__tar.gz → 2.3.0__tar.gz

{binarycookies-2.2.3 → binarycookies-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: binarycookies
-Version: 2.2.3
+Version: 2.3.0
 Summary: Python Binary Cookies (de)serializer
 Author: Daniel Tom
 Author-email: d.e.tom89@gmail.com
@@ -11,7 +11,7 @@ Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Requires-Dist: pydantic (>=2.0.0,<3.0.0)
-Requires-Dist: typer (>=0.12.3,<0.20.0)
+Requires-Dist: typer (>=0.12.3,<0.21.0)
 Description-Content-Type: text/markdown
 
 [![Github Actions Status](https://github.com/dan1elt0m/binary-cookies-reader/workflows/test/badge.svg)](https://github.com/dan1elt0m/binary-cookies-reader/actions/workflows/test.yml)

{binarycookies-2.2.3 → binarycookies-2.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "binarycookies"
-version = "2.2.3"
+version = "2.3.0"
 description = "Python Binary Cookies (de)serializer"
 authors = ["Daniel Tom <d.e.tom89@gmail.com>"]
 readme = "README.md"
@@ -8,7 +8,7 @@ packages = [{include = "binarycookies", from="src"}]
 
 [tool.poetry.dependencies]
 python = ">=3.8,<4.0"
-typer = ">=0.12.3,<0.20.0"
+typer = ">=0.12.3,<0.21.0"
 pydantic = ">=2.0.0,<3.0.0"
 
 [tool.poetry.group.dev.dependencies]

{binarycookies-2.2.3 → binarycookies-2.3.0}/setup.py

@@ -11,14 +11,14 @@ package_data = \
 {'': ['*']}
 
 install_requires = \
-['pydantic>=2.0.0,<3.0.0', 'typer>=0.12.3,<0.20.0']
+['pydantic>=2.0.0,<3.0.0', 'typer>=0.12.3,<0.21.0']
 
 entry_points = \
 {'console_scripts': ['bcparser = binarycookies.__main__:main']}
 
 setup_kwargs = {
     'name': 'binarycookies',
-    'version': '2.2.3',
+    'version': '2.3.0',
     'description': 'Python Binary Cookies (de)serializer',
     'long_description': '[![Github Actions Status](https://github.com/dan1elt0m/binary-cookies-reader/workflows/test/badge.svg)](https://github.com/dan1elt0m/binary-cookies-reader/actions/workflows/test.yml)\n<h1>\n  <img src="docs/bincook.png" width="30" style="vertical-align: middle; margin-right: 10px;">\n  Binary Cookies\n</h1>\n\nCLI tool and Python library for reading and writing Binary Cookies.\n\n### Documentation\nFor detailed documentation, please visit the [Binary Cookies Documentation](https://dan1elt0m.github.io/binarycookies/)\n\n### Requirements\n\n- Python >= 3.9\n\n### Installation\n```bash \npip install binarycookies\n```\n\n### CLI example:\n```sh\nbcparser path/to/cookies.binarycookies\n```\n\nOutput:\n```json\n[\n  {\n    "name": "session_id",\n    "value": "abc123",\n    "url": "https://example.com",\n    "path": "/",\n    "create_datetime": "2023-10-01T12:34:56+00:00",\n    "expiry_datetime": "2023-12-31T23:59:59+00:00",\n    "flag": "Secure"\n  },\n  {\n    "name": "user_token",\n    "value": "xyz789",\n    "url": "https://example.com",\n    "path": "/account",\n    "create_datetime": "2023-10-01T12:34:56+00:00",\n    "expiry_datetime": "2023-12-31T23:59:59+00:00",\n    "flag": "HttpOnly"\n  }\n]\n```\n#### Output formats\nThe CLI supports multiple output formats using the --output flag.\n- `json` (default): Outputs cookies in JSON format.\n- `ascii`: Outputs cookies in a human-readable ASCII format with each cookie property on a separate line.\n- `netscape`: Outputs cookies in the Netscape cookie file format.\n\n### Basic Usage Python\n\n#### Deserialization\n\n```python\nimport binarycookies \n\nwith open("path/to/cookies.binarycookies", "rb") as f:\n    cookies = binarycookies.load(f)\n```\n\n#### Serialization\n\n```python\nimport binarycookies \n\ncookie = {\n    "name": "session_id",\n    "value": "abc123",\n    "url": "https://example.com",\n    "path": "/",\n    "create_datetime": "2023-10-01T12:34:56+00:00",\n    "expiry_datetime": "2023-12-31T23:59:59+00:00",\n    "flag": "Secure"\n}\n\nwith open("path/to/cookies.binarycookies", "wb") as f:\n    binarycookies.dump(cookie, f)\n```\n\n### Ethical Use & Responsible Handling\nThis project is intended for lawful, ethical use only. Typical, appropriate uses include:\n- Inspecting Binary Cookies from your own devices or data you are authorized to access\n- DFIR, QA, and security testing performed with explicit, written permission\n- Educational/research work on datasets that are owned by you, anonymized, or publicly released for that purpose\n\nYou must not use this tool to:\n- Access, extract, modify, or distribute cookies from systems or accounts you do not own or have permission to analyze\n- Bypass authentication, session management, DRM, or other technical controls\n- Enable tracking, stalking, doxxing, fraud, or other privacy-invasive or harmful activities\n\n\n### License\nThis project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.\n\n### Contributing\nContributions are welcome! If you find a bug or have a feature request, please open an issue on GitHub. Pull requests are also welcome.\n',
     'author': 'Daniel Tom',

binarycookies-2.3.0/src/binarycookies/__init__.py

@@ -0,0 +1,12 @@
+from importlib.metadata import PackageNotFoundError, version
+
+from binarycookies._deserialize import load, loads
+from binarycookies._serialize import dump, dumps
+
+try:
+    __version__ = version("binarycookies")
+except PackageNotFoundError:
+    # Package is not installed, fallback to a default
+    __version__ = "0.0.0+unknown"
+
+__all__ = ["dump", "dumps", "load", "loads"]

{binarycookies-2.2.3 → binarycookies-2.3.0}/src/binarycookies/__main__.py

@@ -1,11 +1,11 @@
 import json
 from datetime import datetime
-from typing import Type
+from typing import Optional, Type
 
 import typer
 from rich import print as rprint
 
-from binarycookies import load
+from binarycookies import __version__, load
 from binarycookies._output_handlers import OUTPUT_HANDLERS, OutputType
 
 
@@ -16,7 +16,24 @@ class DateTimeEncoder(json.JSONEncoder):
         return super().default(obj)
 
 
-def cli(file_path: str, output: OutputType = OutputType.json):
+app = typer.Typer()
+
+
+def version_callback(value: bool):  # noqa: FBT001
+    """Callback to print version and exit."""
+    if value:
+        rprint(f"binarycookies version {__version__}")
+        raise typer.Exit
+
+
+@app.command()
+def cli(
+    file_path: str = typer.Argument(..., help="Path to binary cookies file"),
+    output: OutputType = typer.Option(OutputType.json, "--output", "-o", help="Output format"),
+    version: Optional[bool] = typer.Option(  # noqa: ARG001
+        None, "--version", "-v", callback=version_callback, is_eager=True, help="Show version and exit"
+    ),
+):
     """CLI entrypoint for reading Binary Cookies"""
     with open(file_path, "rb") as f:
         cookies = load(f)
@@ -31,7 +48,7 @@ def cli(file_path: str, output: OutputType = OutputType.json):
 
 def main():
     """CLI entrypoint for reading Binary Cookies"""
-    typer.run(cli)
+    app()
 
 
 if __name__ == "__main__":

{binarycookies-2.2.3 → binarycookies-2.3.0}/src/binarycookies/_deserialize.py

@@ -86,6 +86,10 @@ def read_cookie(cookie: BytesIO, cookie_size: int) -> Cookie:
     flag_int = read_field(cookie, cookie_fields.flag)
     flag = interpret_flag(flag_int)
 
+    # Read comment offset at offset 32
+    cookie.seek(32)
+    comment_offset = unpack(Format.integer, cookie.read(4))[0]  # noqa: F841
+
     url_offset = read_field(cookie, cookie_fields.url_offset)
     name_offset = read_field(cookie, cookie_fields.name_offset)
     path_offset = read_field(cookie, cookie_fields.path_offset)
@@ -94,6 +98,7 @@ def read_cookie(cookie: BytesIO, cookie_size: int) -> Cookie:
     expiry_datetime = mac_epoch_to_date(read_field(cookie, cookie_fields.expiry_date))
     create_datetime = mac_epoch_to_date(read_field(cookie, cookie_fields.create_date))
 
+    # Read strings - comment comes first, then domain (url)
     url = read_field(cookie, BcField(offset=url_offset, size=name_offset - url_offset, format=Format.string))
     name = read_field(cookie, BcField(offset=name_offset, size=path_offset - name_offset, format=Format.string))
     path = read_field(cookie, BcField(offset=path_offset, size=value_offset - path_offset, format=Format.string))

binarycookies-2.3.0/src/binarycookies/_serialize.py

@@ -0,0 +1,222 @@
+from datetime import datetime, timezone
+from io import BufferedWriter, BytesIO
+from struct import pack
+from typing import BinaryIO, Dict, List, Tuple, Union
+
+from pydantic import __version__ as pydantic_version
+
+from binarycookies._deserialize import FLAGS
+from binarycookies.models import BcField, Cookie, CookieFields, FileFields, Format
+
+IS_PYDANTIC_V1 = pydantic_version.startswith("1.")
+
+CookiesCollection = Union[List[Dict], List[Cookie], Tuple[Dict], Tuple[Cookie], Cookie, Dict[str, str]]
+
+
+def date_to_mac_epoch(date: datetime) -> int:
+    """Converts a datetime object to mac epoch time."""
+    mac_epoch_start = datetime(2001, 1, 1, tzinfo=timezone.utc)
+    return int((date - mac_epoch_start).total_seconds())
+
+
+def write_string(data: BytesIO, value: str):
+    """Writes a string to binary file."""
+    data.write(value.encode() + b"\x00")
+
+
+def write_field(data: BytesIO, field: BcField, value: Union[str, int]):
+    """Writes a field to binary data."""
+    data.seek(field.offset)
+    if field.format == Format.string:
+        write_string(data, value)
+    else:
+        data.write(pack(field.format, value))
+
+
+def serialize_cookie(cookie: Cookie) -> bytes:
+    """Serializes a cookie object to binary format."""
+    cookie_fields = CookieFields()
+
+    # Pre-calculate the size to allocate buffer
+    # Cookie header is 60 bytes according to spec:
+    # 0-3: size, 4-7: unknownOne, 8-11: flags, 12-15: unknownTwo
+    # 16-19: domainOffset, 20-23: nameOffset, 24-27: pathOffset, 28-31: valueOffset
+    # 32-35: commentOffset, 36-39: endHeader
+    # 40-47: expires, 48-55: creation
+    # 56-59: comment (empty), 60+: domain, name, path, value strings
+    url_bytes = cookie.url.encode("utf-8")
+    name_bytes = cookie.name.encode("utf-8")
+    path_bytes = cookie.path.encode("utf-8")
+    value_bytes = cookie.value.encode("utf-8")
+    comment_bytes = b""  # Empty comment
+
+    # Each string has a null terminator
+    header_size = 60
+    strings_size = (
+        len(comment_bytes) + 1 + len(url_bytes) + 1 + len(name_bytes) + 1 + len(path_bytes) + 1 + len(value_bytes) + 1
+    )
+    total_size = header_size + strings_size
+
+    # Pre-allocate buffer with zeros
+    cookie_data = BytesIO(b"\x00" * total_size)
+
+    # Write flag
+    write_field(cookie_data, cookie_fields.flag, list(FLAGS.keys())[list(FLAGS.values()).index(cookie.flag)])
+
+    # Calculate offsets - strings start at byte 60 after header
+    comment_offset = 60
+    domain_offset = comment_offset + len(comment_bytes) + 1  # +1 for null terminator
+    name_offset = domain_offset + len(url_bytes) + 1
+    path_offset = name_offset + len(name_bytes) + 1
+    value_offset = path_offset + len(path_bytes) + 1
+
+    # Write offsets (note: spec calls it domain but code uses url)
+    write_field(cookie_data, cookie_fields.url_offset, domain_offset)
+    write_field(cookie_data, cookie_fields.name_offset, name_offset)
+    write_field(cookie_data, cookie_fields.path_offset, path_offset)
+    write_field(cookie_data, cookie_fields.value_offset, value_offset)
+
+    # Write commentOffset at offset 32
+    cookie_data.seek(32)
+    cookie_data.write(pack(Format.integer, comment_offset))
+
+    # Write endHeader marker at offset 36 (4 bytes of 0x00)
+    cookie_data.seek(36)
+    cookie_data.write(b"\x00\x00\x00\x00")
+
+    write_field(cookie_data, cookie_fields.expiry_date, date_to_mac_epoch(cookie.expiry_datetime))
+    write_field(cookie_data, cookie_fields.create_date, date_to_mac_epoch(cookie.create_datetime))
+
+    # Write string data starting at offset 60
+    cookie_data.seek(60)
+    # Write comment (empty string with null terminator)
+    write_string(cookie_data, "")
+    # Write domain (url), name, path, value
+    write_string(cookie_data, cookie.url)
+    write_string(cookie_data, cookie.name)
+    write_string(cookie_data, cookie.path)
+    write_string(cookie_data, cookie.value)
+
+    # Write size at the beginning
+    size = len(cookie_data.getvalue())
+    cookie_data.seek(0)
+    cookie_data.write(pack(Format.integer, size))
+    return cookie_data.getvalue()
+
+
+def dump(cookies: CookiesCollection, f: Union[BufferedWriter, BytesIO, BinaryIO]):
+    """Dumps a Binary Cookies object to create a binary cookies file.
+
+    Args:
+        cookies: A Binary Cookies object to be serialized.
+        f: The file-like object to write the binary cookies data to.
+    """
+    binary = dumps(cookies)
+    f.write(binary)
+
+
+def calculate_checksum(page_data: bytes) -> int:
+    """Calculates the checksum by summing every 4th byte of the page data.
+
+    Args:
+        page_data: The raw bytes of a page.
+    Returns:
+        int: The checksum value.
+    """
+    checksum = 0
+    # Sum every 4th byte (bytes at positions 0, 4, 8, 12, ...)
+    for i in range(0, len(page_data), 4):
+        checksum += page_data[i]
+    return checksum
+
+
+def dumps(cookies: CookiesCollection) -> bytes:
+    """Dumps a Binary Cookies object to a byte string.
+
+    Args:
+        cookies: A Binary Cookies object to be serialized.
+    Returns:
+        bytes: The serialized binary cookies data.
+    """
+    if isinstance(cookies, dict):
+        cookies = [Cookie.parse_obj(cookies)] if IS_PYDANTIC_V1 else [Cookie.model_validate(cookies)]
+    elif isinstance(cookies, (list, tuple)):
+        if IS_PYDANTIC_V1:
+            cookies = [Cookie.parse_obj(cookie) for cookie in cookies]
+        else:
+            cookies = [Cookie.model_validate(cookie) for cookie in cookies]
+    elif isinstance(cookies, Cookie):
+        cookies = [cookies]
+    else:
+        raise TypeError("Invalid type for cookies. Expected dict, list, tuple, or Cookie.")
+
+    file_fields = FileFields()
+
+    data = BytesIO()
+
+    # Write file header (4 bytes: "cook")
+    data.write(b"cook")
+
+    # Number of pages (1 for simplicity, big-endian)
+    write_field(data, file_fields.num_pages, 1)
+
+    # Write page size pointer
+    data.write(pack(Format.integer, 0))  # Placeholder, will be updated
+
+    # Store the position where page data starts
+    page_start_offset = data.tell()
+    page_data = BytesIO()
+
+    # Write pageStart marker (4 bytes) - Must be 0x00, 0x01, 0x00, 0x00
+    page_data.write(b"\x00\x01\x00\x00")
+
+    # Write number of cookies in the page
+    page_data.write(pack(Format.integer, len(cookies)))
+
+    cookie_data_list = []
+    # Serialize cookies
+    for cookie in cookies:
+        cookie_data_list.append(serialize_cookie(cookie))
+
+    # Calculate where cookie data will start:
+    # current position + (num_cookies * 4 bytes for offsets) + 4 bytes for pageEnd marker
+    initial_cookie_offset = page_data.tell() + (len(cookies) * 4) + 4
+    initial_cookie = True
+    previous_sizes = 0
+
+    # Write cookie offsets
+    for cookie_data in cookie_data_list:
+        if initial_cookie:
+            page_data.write(pack(Format.integer, initial_cookie_offset))
+            initial_cookie = False
+        else:
+            page_data.write(pack(Format.integer, previous_sizes + initial_cookie_offset))
+
+        previous_sizes += len(cookie_data)
+
+    # Write pageEnd marker (4 bytes) - Must be 0x00, 0x00, 0x00, 0x00
+    page_data.write(b"\x00\x00\x00\x00")
+
+    # Write cookie data
+    for cookie_data in cookie_data_list:
+        page_data.write(cookie_data)
+
+    # Get the complete page data
+    page_bytes = page_data.getvalue()
+    page_size = len(page_bytes)
+
+    # Update page size in the file header (big-endian format for page sizes)
+    data.seek(8)
+    data.write(pack(Format.integer_be, page_size))
+
+    # Write the page data
+    data.seek(page_start_offset)
+    data.write(page_bytes)
+
+    # Calculate and write checksum after all pages
+    # The checksum is the sum of every 4th byte of the page data
+    # Specification says 8 bytes, so we write it as a 64-bit integer
+    checksum = calculate_checksum(page_bytes)
+    data.write(pack("<Q", checksum))  # LE_uint64 (8 bytes)
+
+    return data.getvalue()

binarycookies-2.2.3/src/binarycookies/__init__.py

@@ -1,4 +0,0 @@
-from binarycookies._deserialize import load, loads
-from binarycookies._serialize import dump, dumps
-
-__all__ = ["dump", "dumps", "load", "loads"]

binarycookies-2.2.3/src/binarycookies/_serialize.py

@@ -1,150 +0,0 @@
-from datetime import datetime, timezone
-from io import BufferedWriter, BytesIO
-from struct import pack
-from typing import BinaryIO, Dict, List, Tuple, Union
-
-from pydantic import __version__ as pydantic_version
-
-from binarycookies._deserialize import FLAGS
-from binarycookies.models import BcField, Cookie, CookieFields, FileFields, Format
-
-IS_PYDANTIC_V1 = pydantic_version.startswith("1.")
-
-CookiesCollection = Union[List[Dict], List[Cookie], Tuple[Dict], Tuple[Cookie], Cookie, Dict[str, str]]
-
-
-def date_to_mac_epoch(date: datetime) -> int:
-    """Converts a datetime object to mac epoch time."""
-    mac_epoch_start = datetime(2001, 1, 1, tzinfo=timezone.utc)
-    return int((date - mac_epoch_start).total_seconds())
-
-
-def write_string(data: BytesIO, value: str):
-    """Writes a string to binary file."""
-    data.write(value.encode() + b"\x00")
-
-
-def write_field(data: BytesIO, field: BcField, value: Union[str, int]):
-    """Writes a field to binary data."""
-    data.seek(field.offset)
-    if field.format == Format.string:
-        write_string(data, value)
-    else:
-        data.write(pack(field.format, value))
-
-
-def serialize_cookie(cookie: Cookie) -> bytes:
-    """Serializes a cookie object to binary format."""
-    cookie_data = BytesIO()
-    cookie_fields = CookieFields()
-    # Write flag
-    write_field(cookie_data, cookie_fields.flag, list(FLAGS.keys())[list(FLAGS.values()).index(cookie.flag)])
-
-    # Calculate offsets
-    url_offset = 56  # The actual cookies content always starts at byte 56
-    name_offset = 1 + url_offset + len(cookie.url.encode("utf-8"))
-    path_offset = 1 + name_offset + len(cookie.name.encode("utf-8"))
-    value_offset = 1 + path_offset + len(cookie.path.encode("utf-8"))
-
-    write_field(cookie_data, cookie_fields.url_offset, url_offset)
-    write_field(cookie_data, cookie_fields.name_offset, name_offset)
-    write_field(cookie_data, cookie_fields.path_offset, path_offset)
-    write_field(cookie_data, cookie_fields.value_offset, value_offset)
-
-    write_field(cookie_data, cookie_fields.expiry_date, date_to_mac_epoch(cookie.expiry_datetime))
-    write_field(cookie_data, cookie_fields.create_date, date_to_mac_epoch(cookie.create_datetime))
-
-    # Write cookie data
-    write_string(cookie_data, cookie.url)
-    write_string(cookie_data, cookie.name)
-    write_string(cookie_data, cookie.path)
-    write_string(cookie_data, cookie.value)
-
-    # Write size at the beginning
-    size = len(cookie_data.getvalue())
-    cookie_data.seek(0)
-    cookie_data.write(pack(Format.integer, size))
-    return cookie_data.getvalue()
-
-
-def dump(cookies: CookiesCollection, f: Union[BufferedWriter, BytesIO, BinaryIO]):
-    """Dumps a Binary Cookies object to create a binary cookies file.
-
-    Args:
-        cookies: A Binary Cookies object to be serialized.
-        f: The file-like object to write the binary cookies data to.
-    """
-    binary = dumps(cookies)
-    f.write(binary)
-
-
-def dumps(cookies: CookiesCollection) -> bytes:
-    """Dumps a Binary Cookies object to a byte string.
-
-    Args:
-        cookies: A Binary Cookies object to be serialized.
-    Returns:
-        bytes: The serialized binary cookies data.
-    """
-    if isinstance(cookies, dict):
-        cookies = [Cookie.parse_obj(cookies)] if IS_PYDANTIC_V1 else [Cookie.model_validate(cookies)]
-    elif isinstance(cookies, (list, tuple)):
-        if IS_PYDANTIC_V1:
-            cookies = [Cookie.parse_obj(cookie) for cookie in cookies]
-        else:
-            cookies = [Cookie.model_validate(cookie) for cookie in cookies]
-    elif isinstance(cookies, Cookie):
-        cookies = [cookies]
-    else:
-        raise TypeError("Invalid type for cookies. Expected dict, list, tuple, or Cookie.")
-
-    file_fields = FileFields()
-
-    data = BytesIO()
-
-    # Write file header
-    write_field(data, file_fields.header, "cook")
-
-    # Number of pages (1 for simplicity)
-    write_field(data, file_fields.num_pages, 1)
-
-    # Write number of cookies
-    data.write(pack(Format.integer, len(cookies)))
-
-    # Placeholder for page size
-    page_size_offset = data.tell()
-    data.write(b"\x00\x00\x00\x00")
-
-    # Write number of cookies
-    data.write(pack(Format.integer, len(cookies)))
-    cookie_data_list = []
-    # Write cookies
-    for cookie in cookies:
-        cookie_data_list.append(serialize_cookie(cookie))
-
-    initial_cookie_offset = data.tell() + (len(cookies) * 4)
-    initial_cookie = True
-    previous_sizes = 0
-    for cookie_data in cookie_data_list:
-        if initial_cookie:
-            data.write(pack(Format.integer, initial_cookie_offset))
-            initial_cookie = False
-        else:
-            data.write(pack(Format.integer, previous_sizes + initial_cookie_offset))
-
-        previous_sizes += len(cookie_data)
-
-    # Unknown data
-    data.write(b"\x00\x00\x00\x00")
-    data.write(b"\x00\x00\x00\x00")
-    data.write(b"\x00\x00\x00\x00")
-
-    for cookie_data in cookie_data_list:
-        data.write(cookie_data)
-
-    # Update page size
-    page_size = data.tell()
-    data.seek(page_size_offset)
-    data.write(pack(Format.integer, page_size))
-
-    return data.getvalue()