upk-tool 0.1.0

Inspect, extract, and create UGREEN NAS .upk package files

upk-tool

Inspect, extract, and create UGREEN NAS .upk package files (UGREEN-PKG-V2-FORMAT).

What is a .upk file?

.upk files are application packages used by UGREEN NAS devices. They contain:

• Cryptographic signatures (RSA-2048) for file integrity and authenticity
• Public keys for signer and manufacturer verification
• App icon (PNG)
• App payload (gzip → tar → XZ → tar with app binaries, configs, web UI)
• Hash chain for additional integrity verification

Format structure

UGREEN-PKG-V2-FORMAT
filesig:344:<base64 RSA signature>
userpub:392:<base64 DER public key>
usersig:344:<base64 RSA signature>
midpub:392:<base64 DER public key>
midsig:344:<base64 RSA signature>
ico:31350:<raw PNG binary>
ugb:15608334:<gzip compressed tar>
obj2:10204:<hex hash chain>

Each field follows the pattern key:length:value where length is the byte count of value.

Installation

pip install upk-tool

For signing support:

pip install upk-tool[signing]

Usage

Inspect a .upk file

upk-tool verify firmware.upk

Output:

File: firmware.upk
Fields: 8
  filesig: 344 bytes
  userpub: 392 bytes
  usersig: 344 bytes
  midpub: 392 bytes
  midsig: 344 bytes
  ico: 31350 bytes
  ugb: 15608334 bytes
  obj2: 10204 bytes

  ugb contents (gzip tar): 2 entries
    uninstall.sh (657 bytes)
    com.ugreen.comic.ugb (15602856 bytes)
    -> com.ugreen.comic.ugb: XZ -> tar with 64 files

Signature verification:
  filesig: 256 bytes (RSA-2048)
  usersig: 256 bytes (RSA-2048)
  midsig: 256 bytes (RSA-2048)
  userpub: 294 bytes DER
  midpub: 294 bytes DER

Extract a .upk file

upk-tool extract firmware.upk -o extracted/

This will:

1. Save all raw fields to the output directory
2. Create metadata.json with field metadata
3. Decompress the ugb payload (gzip → tar)
4. Decompress inner .ugb files (XZ → tar)
5. Extract the final app contents

Directory structure:

extracted/
├── metadata.json
├── ico.bin
├── ugb.bin
└── ugb_contents/
    ├── uninstall.sh
    ├── com.ugreen.app.ugb
    ├── com.ugreen.app_files.tar
    └── com.ugreen.app_app/
        ├── sbin/
        │   └── my_service
        ├── config.json
        ├── www/
        │   └── assets/
        └── ...

Create a .upk file

upk-tool create ./my_app/ -o my_app.upk --icon icon.png --name myapp

Options:

• --icon - PNG icon file (optional, uses 1x1 placeholder if omitted)
• --name - App name used in the package (default: app)
• --uninstall - Custom uninstall script (optional)
• --user-key - RSA private key for user signing (PEM format)
• --mfg-key - RSA private key for manufacturer signing (PEM format)

Create a signed .upk file

# Generate keys (for testing)
openssl genrsa -out user_key.pem 2048
openssl genrsa -out mfg_key.pem 2048

# Create signed package
upk-tool create ./my_app/ \
    -o my_app.upk \
    --icon icon.png \
    --name myapp \
    --user-key user_key.pem \
    --mfg-key mfg_key.pem

Note: Without real UGREEN private keys, the package will have valid structure but signatures won't verify on actual hardware.

Python API

from upk_tool import parse_upk, extract_upk, create_upk, verify_upk

# Parse and inspect
fields = parse_upk("firmware.upk")
print(fields.keys())  # ['filesig', 'userpub', 'usersig', ...]

# Extract
extract_upk("firmware.upk", "output_dir/")

# Create
create_upk(
    app_dir="./my_app/",
    output_path="output.upk",
    icon_path="icon.png",
    app_name="myapp",
)

# Verify/inspect
verify_upk("firmware.upk")

Development

# Clone and install in development mode
git clone https://github.com/anomalyco/oc_analyze_ugreen_upk_package_file.git
cd oc_analyze_ugreen_upk_package_file
pip install -e ".[dev]"

# Run tests
pytest

# Build package
python -m build

# Upload to PyPI
twine upload dist/*

License

MIT