device-fingerprinting-pro 2.2.3

Hardware device fingerprinting with post-quantum cryptography, TPM support, and ML-based anomaly detection

Device Fingerprinting Pro

Production-ready Python library for hardware-based device fingerprinting with post-quantum cryptography, ML anomaly detection, and TPM integration.

Documentation: For detailed documentation and examples, visit the GitHub Repository

---

Table of Contents

Click to expand

• Hello World
• Why This Library?
• Overview
• Quick Start
• Core Features
• Architecture
• Security Model
• Advanced Usage
• Use Cases
• Technical Specifications
• Dependencies
• Testing
• Troubleshooting
• Performance Optimization

---

Hello World

from device_fingerprinting.production_fingerprint import ProductionFingerprintGenerator

generator = ProductionFingerprintGenerator()
fingerprint = generator.generate_fingerprint()

print(fingerprint['fingerprint_hash'])

---

Why This Library?

FingerprintJS and Browser Fingerprinting

• Hardware-level identification
• Post-quantum cryptography (SHA3-512)
• Server-side processing

Generic Device ID Libraries

• ML Anomaly Detection for behavioral analysis
• Encrypted Storage with OS keyring integration
• TPM/Secure Hardware backing (Windows, macOS, Linux)
• Deterministic fingerprinting

TPM Attestation Tools

• Cross-platform TPM support (Windows, macOS, Linux)
• Software fallback mode
• ML-based anomaly detection
• Secure storage for keys and sensitive data
• Comprehensive test suite

Key Differentiators

Feature	Device FP Pro	FingerprintJS	Generic ID	TPM Tools
Post-Quantum Crypto	Yes	No	No	Yes
ML Anomaly Detection	Yes	No	No	No
Cross-platform TPM	Yes	No	No	Yes
Secure Storage	Yes	No	Yes	No
Hardware-Backed	Yes	No	No	Yes
Encryption	Yes	No	No	No

Overview

Provides the following components:

• Hardware fingerprinting for device identification
• Cryptographic operations with AES-GCM and SHA3-512
• ML-based anomaly detection
• Secure storage with OS keyring integration
• Support for Windows, macOS, and Linux

Quick Start

Installation

# Basic installation
pip install device-fingerprinting-pro

# With post-quantum cryptography
pip install device-fingerprinting-pro[pqc]

# With cloud storage support
pip install device-fingerprinting-pro[cloud]

# Full installation
pip install device-fingerprinting-pro[pqc,cloud,dev]

Basic Usage

from device_fingerprinting.production_fingerprint import ProductionFingerprintGenerator

# Generate device fingerprint
generator = ProductionFingerprintGenerator()
fingerprint_data = generator.generate_fingerprint()

print(f"Fingerprint: {fingerprint_data['fingerprint_hash']}")
print(f"Platform: {fingerprint_data['system_info']['platform']}")
print(f"CPU: {fingerprint_data['hardware_info']['cpu_model']}")

Output:

{
    'fingerprint_hash': 'sha3_512_hash_value...',
    'hardware_info': {
        'cpu_model': 'Intel Core i7-9750H',
        'cpu_cores': 6,
        'mac_addresses': ['00:1B:44:11:3A:B7'],
        'disk_serials': ['S3Z3NY0M123456']
    },
    'system_info': {
        'platform': 'Windows-10-...',
        'python_version': '3.11.0'
    }
}

Core Features

1. Device Fingerprinting

Generate stable, unique device identifiers from hardware characteristics:

• Data Sources: CPU model, MAC addresses, disk serials, OS details
• Hash Algorithm: SHA3-512 (quantum-resistant)
• Properties: Stable across reboots, deterministic, collision-resistant

Process Flow:

Hardware Data → Normalization → Sorting → SHA3-512 → Fingerprint Hash

2. TPM/Secure Hardware Fingerprinting

Hardware-backed device identification with dual-mode enforcement:

Mode A: Software (Default) - Optional TPM with fallback

import device_fingerprinting as df

# Enable TPM if available (graceful fallback)
df.enable_tpm_fingerprinting(enabled=True)
fingerprint = df.generate_fingerprint(method="stable", mode="software")

Mode B: TPM-Strict - Mandatory TPM requirement

import device_fingerprinting as df

# Enforce TPM hardware attestation (fails if unavailable)
try:
    fingerprint = df.generate_fingerprint(method="stable", mode="tpm_strict")
except RuntimeError as e:
    print(f"TPM required: {e}")

Platform Support:

• Windows: TPM 2.0 (PowerShell/WMI)
• macOS: Secure Enclave (T2/Apple Silicon)
• Linux: TPM 2.0 (/sys/class/tpm)

3. Secure Storage

Encrypted key-value storage with OS keyring integration:

from device_fingerprinting.secure_storage import SecureStorage

# Initialize storage
storage = SecureStorage(
    storage_path="./secure_data",
    service_name="my_app",
    username="device_001"
)

# Store encrypted data
storage.set_item("api_key", "secret_value")
api_key = storage.get_item("api_key")

# List and delete
keys = storage.list_keys()
storage.delete_item("api_key")

Security Features:

• AES-GCM authenticated encryption
• Scrypt KDF for key derivation
• OS keyring integration (Windows Credential Manager, macOS Keychain, Linux Secret Service)
• No plaintext storage

3. Anomaly Detection

ML-based detection of suspicious system behavior:

from device_fingerprinting.ml_features import FeatureExtractor, AnomalyDetector
import numpy as np

# Train on baseline data
normal_data = np.random.rand(100, 3)  # [cpu%, memory%, battery%]
detector = AnomalyDetector()
detector.train(normal_data)

# Monitor system
extractor = FeatureExtractor()
current_features = extractor.collect_features()
prediction, score = detector.predict(current_features)

if prediction == -1:
    print(f"⚠ Anomaly detected (score: {score:.2f})")
else:
    print(f"✓ Normal behavior (score: {score:.2f})")

# Save/load model
detector.save_model("baseline.pkl")
detector.load_model("baseline.pkl")

Detection Capabilities:

• Debugger and reverse engineering detection
• Virtual machine identification
• System tampering indicators
• Abnormal resource usage patterns

Architecture

System Components

┌─────────────────────────────────────────────────────────┐
│                   Your Application                       │
└────────────────┬────────────────────────────────────────┘
                 │
        ┌────────┴────────┐
        │  API Layer      │
        │  - Fingerprint  │
        │  - Security     │
        │  - Storage      │
        └────────┬────────┘
                 │
    ┌────────────┼────────────┐
    │            │            │
┌───▼───┐   ┌───▼───┐   ┌───▼────┐
│Crypto │   │  ML   │   │Storage │
│Engine │   │Anomaly│   │Manager │
└───────┘   └───────┘   └────────┘
    │            │            │
    └────────────┼────────────┘
                 │
        ┌────────┴────────┐
        │  Data Collection│
        │  - CPU Info     │
        │  - MAC Address  │
        │  - Disk Serial  │
        │  - System Stats │
        └─────────────────┘

Security Stack

Layer	Technology	Purpose
Hashing	SHA3-512	Fingerprint generation
Encryption	AES-GCM-256	Data at rest encryption
KDF	Scrypt	Password-based key derivation
Storage	OS Keyring	Secure credential management
ML	IsolationForest	Anomaly detection

Security Model

Threat Model

Addresses the following threats:

• Unauthorized device impersonation
• Data tampering
• Key extraction
• Anomalous system behavior
• Quantum attacks

Out of scope:

• Compromised OS kernel
• Physical hardware attacks
• User credential compromise

Attack Surfaces & Mitigations

Attack Surface	Description	Mitigation
Storage	Encrypted data at rest	AES-GCM with OS keyring integration
Transmission	Data in transit	Use HTTPS/TLS (application responsibility)
Fingerprint Leakage	Exposed device IDs	Hash-based (collision-resistant SHA3-512)
Key Derivation	Weak key generation	Scrypt with memory-hard parameters
ML Model Inversion	Reversing anomaly detector	Black-box output only (no model exposure)

Security Guarantees

This library provides:

• Deterministic fingerprints (same hardware produces same ID)
• Collision-resistant fingerprints (SHA3-512, 256-bit security)
• Encrypted storage with authenticated encryption (AES-GCM)
• Secure key derivation (Scrypt, memory-hard)
• ML-based behavioral anomaly detection
• No plaintext storage of sensitive data

This library does not provide:

• Protection against compromised OS kernel
• Protection against physical hardware attacks
• Perfect fingerprint uniqueness
• Quantum security for previously-collected encrypted data
• Privacy isolation when device ID is linked to user identity

Privacy Considerations

Data Collection:

• Collects: CPU model, MAC addresses, disk serials, OS info
• Does NOT collect: Browser cookies, IP geolocation, user behavior
• Does NOT transmit data (local processing only)

Hashing & Anonymization:

• All fingerprints are SHA3-512 hashed (one-way, non-reversible)
• Hardware details are not exposed in the hash
• Can't reverse engineer device specs from fingerprint

Storage Privacy:

• All encrypted data uses OS-specific secure storage
• Windows: Credential Manager (DPAPI-backed)
• macOS: Keychain
• Linux: Secret Service / KWallet

---

Complete Integration Example

from device_fingerprinting.production_fingerprint import ProductionFingerprintGenerator
from device_fingerprinting.ml_features import FeatureExtractor, AnomalyDetector
from device_fingerprinting.secure_storage import SecureStorage
import numpy as np

class DeviceSecurityManager:
    def __init__(self):
        self.generator = ProductionFingerprintGenerator()
        self.storage = SecureStorage("./data", "my_app", "device_001")
        self.detector = AnomalyDetector()
        
    def initialize(self):
        """Initialize security system"""
        # Generate and store fingerprint
        fp = self.generator.generate_fingerprint()
        self.storage.set_item("fingerprint", fp['fingerprint_hash'])
        
        # Train anomaly detector
        baseline = self._collect_baseline()
        self.detector.train(baseline)
        self.detector.save_model("./detector.pkl")
        
        return fp['fingerprint_hash']
    
    def verify_device(self):
        """Verify device hasn't changed"""
        current = self.generator.generate_fingerprint()
        stored = self.storage.get_item("fingerprint")
        return current['fingerprint_hash'] == stored
    
    def check_security(self):
        """Check for anomalies"""
        extractor = FeatureExtractor()
        features = extractor.collect_features()
        prediction, score = self.detector.predict(features)
        
        return {
            'is_normal': prediction == 1,
            'score': score
        }
    
    def _collect_baseline(self, samples=100):
        extractor = FeatureExtractor()
        data = [extractor.collect_features() for _ in range(samples)]
        return np.array(data)

# Usage
manager = DeviceSecurityManager()
device_id = manager.initialize()

# Periodic verification
if manager.verify_device():
    status = manager.check_security()
    if not status['is_normal']:
        print("Security alert: Anomaly detected")

JWT Authentication Integration

from device_fingerprinting.production_fingerprint import ProductionFingerprintGenerator
import jwt
from datetime import datetime, timedelta

def create_device_bound_token(user_id, secret_key):
    """Create JWT bound to device"""
    generator = ProductionFingerprintGenerator()
    device_fp = generator.generate_fingerprint()
    
    payload = {
        'user_id': user_id,
        'device_id': device_fp['fingerprint_hash'],
        'exp': datetime.utcnow() + timedelta(hours=24)
    }
    
    return jwt.encode(payload, secret_key, algorithm='HS256')

def verify_device_bound_token(token, secret_key):
    """Verify JWT and device match"""
    payload = jwt.decode(token, secret_key, algorithms=['HS256'])
    
    generator = ProductionFingerprintGenerator()
    current = generator.generate_fingerprint()
    
    if payload['device_id'] != current['fingerprint_hash']:
        raise SecurityError("Device mismatch detected")
    
    return payload['user_id']

Use Cases

Authentication & Security

• Multi-factor authentication (device-based 2FA)
• Session binding to specific devices
• Account takeover detection
• Credential sharing prevention

Licensing & DRM

• Per-device software licensing
• License key validation
• Installation tracking
• Prevent unauthorized copying

Fraud Detection

• Detect suspicious device changes
• Monitor for automated bots
• Identify virtual machines
• Track device reputation

Compliance & Auditing

• Device access logs
• Compliance reporting
• Track data access by device
• Audit trail generation

Technical Specifications

Hardware Data Collection

Component	Information	Platform Support
CPU	Model, cores, architecture	Windows, macOS, Linux
Network	MAC addresses	Windows, macOS, Linux
Storage	Disk serial numbers	Windows, macOS, Linux
System	OS type, version, hostname	All platforms

Cryptographic Primitives

Algorithm	Key Size	Security Level	Standard
SHA3-512	N/A	256-bit	FIPS 202
AES-GCM	256-bit	256-bit	FIPS 197
Scrypt	256-bit	Memory-hard	RFC 7914

ML Anomaly Detection

• Algorithm: IsolationForest (scikit-learn)
• Features: CPU%, Memory%, Battery%, Network activity
• Training: Minimum 50-100 baseline samples
• Output: Binary classification (-1=anomaly, 1=normal) + anomaly score

Dependencies

Core Requirements

• numpy >= 1.21.0 - Numerical operations
• scikit-learn >= 1.0.0 - Machine learning
• psutil >= 5.8.0 - System metrics
• cryptography >= 41.0.0 - Encryption
• keyring >= 23.0.0 - OS keyring integration

Optional Features

• pqcdualusb >= 0.1.4 - Post-quantum cryptography
• boto3 - AWS S3 integration
• azure-storage-blob - Azure Blob Storage

Testing

Test Suite

• 57 tests covering all core functionality
• 31% code coverage
• Automated CI/CD with GitHub Actions
• Multi-platform testing (Windows, macOS, Linux)
• Multi-version testing (Python 3.9-3.12)

Run Tests

# Install dev dependencies
pip install device-fingerprinting-pro[dev]

# Run tests
pytest

# With coverage
pytest --cov=device_fingerprinting --cov-report=html

Troubleshooting

Common Issues

ImportError: No module named 'sklearn'

pip install scikit-learn>=1.0.0

KeyringError: No backend found (Linux)

sudo apt-get install gnome-keyring
# or
export PYTHON_KEYRING_BACKEND=keyring.backends.null.Keyring

Fingerprint changes after reboot

• Check if MAC addresses are randomized (privacy features)
• Ensure network interfaces have stable ordering
• Verify disk serials are accessible with proper permissions

Anomaly detector reports false positives

• Collect more baseline samples (100+ recommended)
• Train during normal system operation
• Adjust contamination parameter (default: 0.1)

Performance Optimization

Fingerprint Generation:

• Cache results (fingerprints rarely change)
• Use async for network operations
• Skip slow hardware checks if needed

Anomaly Detection:

• Reduce sampling frequency (e.g., every 60s)
• Use pre-trained models
• Batch predictions when possible

Storage Operations:

• Batch writes
• Use in-memory cache for frequent reads
• Compress large data before encryption

Documentation & Support

• GitHub Repository: https://github.com/Johnsonajibi/DeviceFingerprinting
• Full Documentation: https://github.com/Johnsonajibi/DeviceFingerprinting/blob/main/README.md
• Issue Tracker: https://github.com/Johnsonajibi/DeviceFingerprinting/issues
• Changelog: https://github.com/Johnsonajibi/DeviceFingerprinting/blob/main/CHANGELOG.md

Contributing

Contributions welcome! Please see CONTRIBUTING.md

1. Fork the repository
2. Create a feature branch
3. Add tests for new features
4. Submit a pull request

License

MIT License - see LICENSE for details

Changelog

Version 2.2.0 (2025-12-21)

• Added TPM/Secure Hardware fingerprinting support
• Dual-mode architecture: software (default) and tpm_strict (enforced)
• Cross-platform TPM detection (Windows TPM 2.0, macOS Secure Enclave, Linux TPM)
• Hardware attestation with privacy-preserving obfuscation
• Enhanced security for deployment requiring hardware-backed identity

Version 2.0.0 (2025-10-18)

• Initial PyPI release
• Device fingerprinting
• ML-based anomaly detection
• AES-GCM encryption and secure storage
• Cross-platform support (Windows, macOS, Linux)
• Test suite (57 tests)
• CI/CD pipeline with GitHub Actions