@anonympins/fingerprint 0.6.1 β 0.6.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +25 -0
- package/README.md +128 -119
- package/composer.json +2 -1
- package/package.json +1 -1
- package/src/js/fingerprint.client.obfuscated.js +1 -1
- package/src/js/fingerprint.js +452 -109
- package/src/js/library.js +131 -54
- package/src/js/mongodb-store.js +13 -0
- package/src/js/problem-manager.js +6 -2
- package/src/js/redis-store.js +13 -0
- package/src/js/sql-store.js +80 -77
- package/src/js/tests/fingerprint.engine.test.js +2 -3
- package/src/js/tests/fingerprint.test.js +49 -12
- package/src/js/tests/metrics.test.js +157 -103
- package/src/php/Challenge/ChallengeUtils.php +8 -6
- package/src/php/Config/SecurityProfiles.php +8 -2
- package/src/php/FingerprintEngine.php +155 -41
- package/src/php/Optimization/OptimizationOperators.php +60 -36
- package/src/php/RequestContext.php +7 -0
- package/src/php/Store/IStore.php +6 -0
- package/src/php/Store/MongoDbStore.php +12 -0
- package/src/php/Store/RedisStore.php +12 -0
- package/src/php/Tests/ChallengeUtilsTest.php +6 -4
- package/src/php/Tests/FingerprintEngineTest.php +232 -0
- package/src/php/Tests/IpReputationTest.php +1 -0
- package/src/php/Tests/MetricsTest.php +97 -45
- package/src/php/Tests/RequestUtilsTest.php +14 -14
- package/src/php/Tests/config/ed25519_key.json +4 -0
- package/src/php/Utils/Env.php +50 -0
- package/src/php/Utils/MetricsManager.php +209 -166
- package/src/php/Utils/RequestUtils.php +105 -22
package/CHANGELOG.md
CHANGED
|
@@ -1,3 +1,28 @@
|
|
|
1
|
+
## Version 0.6.4
|
|
2
|
+
|
|
3
|
+
- π **IP and TLS Session Binding in CPU Challenge**: Reinforced CPU challenge security by cryptographically binding the client's IP and `tlsSessionId` to the challenge's binary block (`baseBlock`). This effectively prevents replay attacks and the sharing of calculation solutions between distinct sessions or IP addresses.
|
|
4
|
+
- π‘οΈ **Intelligent Filtering and Whitelist Inspection**:
|
|
5
|
+
- **Certain Attack Detection**: Added a mechanism that automatically bypasses the whitelist if an "authorized" client triggers a honeypot or presents obvious bot signatures (`_hasCertainAttack`).
|
|
6
|
+
- **Inspection Thresholds (`filterWhitelist`)**: Ability to inspect and challenge whitelist requests if their suspicion score exceeds a configurable limit (numeric or strict).
|
|
7
|
+
- **Updated Security Profiles**: Default integration of the `filterWhitelist` parameter across all predefined profiles (`balanced` at 85.0, `api` at 75.0, `blog` at 90.0, and `strict` and `ecommerce` set to `true` [strict]).
|
|
8
|
+
- 𧬠**Auto-Tuner Extensions & Log Compression**: Improved the auto-tuning engine to better handle recent log patterns, adaptively optimize configurations, and smooth out transitions with better inertia management.
|
|
9
|
+
- β‘ **Automatic uPoW Updates**: The Auto-Tuner now autonomously updates useful Proof-of-Work (uPoW) task configurations using optimized Pareto fronts.
|
|
10
|
+
- π§Ή **Store Reset on Startup**: Introduced the `reset` configuration option to cleanly empty the active persistence store during the initial instantiation of the fingerprinting engine.
|
|
11
|
+
|
|
12
|
+
## Version 0.6.3
|
|
13
|
+
|
|
14
|
+
- π‘οΈ **Subnet & Botnet Scoring Upgrades**: Refined the IP Subnet reputation score to use an advanced, continuous analog calculation while handling potential `NaN` boundary edge cases. Enhanced the `botnetClusterScore` algorithm to improve grouping and detection precision of clustered threats.
|
|
15
|
+
- π **Persistent Ed25519 Keypair Recovery**: Hardened persistent Ed25519 key loading, generation, and storage, resolving environment variable fallbacks across test environments.
|
|
16
|
+
- More unit tests and java coverage
|
|
17
|
+
- Java : security profiles added (+ wiki update)
|
|
18
|
+
- NodeJS/PHP : All weights in autotuner
|
|
19
|
+
|
|
20
|
+
## Version 0.6.2
|
|
21
|
+
|
|
22
|
+
- π Java security fixes
|
|
23
|
+
- π Updated peer thread list documentation and full options
|
|
24
|
+
- β‘ Added getMetric(name) in each language (with wiki documentation)
|
|
25
|
+
|
|
1
26
|
## Version 0.6.1
|
|
2
27
|
|
|
3
28
|
- **π Asymmetric Keys by Default**: Promoted Ed25519 asymmetric key binding to be active by default for validating stateless challenge tickets and cooperative signatures. This ensures secure, zero-trust validation chains out-of-the-box, preventing client-side decryption or tampering of authorization claims.
|
package/README.md
CHANGED
|
@@ -1,120 +1,129 @@
|
|
|
1
|
-
# Fingerprint
|
|
2
|
-
|
|
3
|
-
NodeJS tests : [](https://github.com/anonympins/fingerprint/actions/workflows/ci-nodejs.yml) / PHP tests : [](https://github.com/anonympins/fingerprint/actions/workflows/ci-php.yml) / Python tests : [](https://github.com/anonympins/fingerprint/actions/workflows/ci-python.yml) / Java tests : [](https://github.com/anonympins/fingerprint/actions/workflows/ci-java.yml)
|
|
4
|
-
|
|
5
|
-
[](https://github.com/anonympins/fingerprint/releases)
|
|
6
|
-
[](https://github.com/anonympins/fingerprint/blob/main/LICENSE)
|
|
7
|
-
[](https://github.com/anonympins/fingerprint)
|
|
9
|
-
|
|
10
|
-
A multi-layered behavioral, cryptographic, and network analysis production-grade engine designed to identify and mitigate malicious requests (bots, scrapers, session hijacking, bot farms) in real-time. Supports **Node.js**, **Java**, **Python** and **PHP** environments.
|
|
11
|
-
|
|
12
|
-
It leverages multi-layer hardware fingerprinting, real-time behavioral analysis, passive network/TLS tracking, and adaptive/useful proof-of-work challenges to dynamically detect and mitigate scraping, scalping, account takeover (ATO), and sophisticated automated threats.
|
|
13
|
-
|
|
14
|
-
Supported officially on **Node.js (>=20.0.0)**, **PHP (>=8.0)**, Java (>=17), and **Python (>=3.8)**.
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
### Presentation video
|
|
19
|
-
|
|
20
|
-
[](https://www.youtube.com/watch?v=Ujeznl0JAl4)
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
## π Key Features
|
|
24
|
-
|
|
25
|
-
### 1. 𧬠Polymorphic Client-Side WASM & JS Solvers
|
|
26
|
-
*
|
|
27
|
-
*
|
|
28
|
-
*
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
*
|
|
33
|
-
*
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
*
|
|
38
|
-
*
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
*
|
|
43
|
-
*
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
*
|
|
48
|
-
*
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
*
|
|
53
|
-
*
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
*
|
|
58
|
-
*
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
###
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
```
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
1
|
+
# Fingerprint Anti-Bot Protection: Secure Your Digital Assets
|
|
2
|
+
|
|
3
|
+
NodeJS tests : [](https://github.com/anonympins/fingerprint/actions/workflows/ci-nodejs.yml) / PHP tests : [](https://github.com/anonympins/fingerprint/actions/workflows/ci-php.yml) / Python tests : [](https://github.com/anonympins/fingerprint/actions/workflows/ci-python.yml) / Java tests : [](https://github.com/anonympins/fingerprint/actions/workflows/ci-java.yml)
|
|
4
|
+
|
|
5
|
+
[](https://github.com/anonympins/fingerprint/releases)
|
|
6
|
+
[](https://github.com/anonympins/fingerprint/blob/main/LICENSE)
|
|
7
|
+
[](https://img.shields.io/npm/dw/%40anonympins%2Ffingerprint)
|
|
8
|
+
[](https://github.com/anonympins/fingerprint)
|
|
9
|
+
|
|
10
|
+
A multi-layered behavioral, cryptographic, and network analysis production-grade engine designed to identify and mitigate malicious requests (bots, scrapers, session hijacking, bot farms) in real-time. Supports **Node.js**, **Java**, **Python** and **PHP** environments.
|
|
11
|
+
|
|
12
|
+
It leverages multi-layer hardware fingerprinting, real-time behavioral analysis, passive network/TLS tracking, and adaptive/useful proof-of-work challenges to dynamically detect and mitigate scraping, scalping, account takeover (ATO), and sophisticated automated threats.
|
|
13
|
+
|
|
14
|
+
Supported officially on **Node.js (>=20.0.0)**, **PHP (>=8.0)**, Java (>=17), and **Python (>=3.8)**.
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
### Presentation video
|
|
19
|
+
|
|
20
|
+
[](https://www.youtube.com/watch?v=Ujeznl0JAl4)
|
|
21
|
+
|
|
22
|
+
|
|
23
|
+
## π Key Features: Stop Automated Threats and Protect Your Business
|
|
24
|
+
|
|
25
|
+
### 1. 𧬠Polymorphic Client-Side WASM & JS Solvers: Outsmart Bot Adaptation
|
|
26
|
+
* **Problem**: Sophisticated bots constantly adapt to your defenses, reverse-engineering client-side code to bypass protection.
|
|
27
|
+
* **Solution**: Our engine dynamically generates unique, randomized client-side code (WebAssembly and JavaScript) for each session. This makes it impossible for bots to fingerprint and consistently bypass your protection, forcing them to constantly re-adapt.
|
|
28
|
+
* **Benefit**: Stay one step ahead of bot developers. Your defenses evolve with every request, making automated attacks economically unviable.
|
|
29
|
+
|
|
30
|
+
### 2. π± Useful Proof-of-Work (uPoW) & PoSpace: Eliminate Bot Farm Profitability
|
|
31
|
+
* **Problem**: Traditional CAPTCHAs and simple PoW puzzles are easily automated or solved by bot farms, leading to high operational costs for you and low costs for attackers.
|
|
32
|
+
* **Solution**: We force suspicious clients to solve complex, real-world optimization problems (e.g., Traveling Salesperson, Fraud Detection parameter tuning) or prove significant storage allocation. This work is valuable to you, and computationally expensive for bot farms.
|
|
33
|
+
* **Benefit**: Turn bot activity into a resource drain for attackers. By making large-scale automated attacks economically unviable, you protect your resources and ensure fair access for legitimate users.
|
|
34
|
+
|
|
35
|
+
### 3. π Passive Network Signature Analysis: Unmask Stealthy Bots
|
|
36
|
+
* **Problem**: Advanced bots try to mimic real browsers, but often fail to replicate genuine network signatures, allowing them to slip past basic defenses.
|
|
37
|
+
* **Solution**: Our engine analyzes deep network layers (TLS, HTTP/2, TCP/IP stack) to identify unique digital fingerprints. This includes inspecting TLS handshake details (JA3/JA4), HTTP/2 settings, and even raw TCP packet characteristics (like TTL and Window Size) to classify the true nature of the client.
|
|
38
|
+
* **Benefit**: Detect and block bots that attempt to spoof their identity at the transport layer, revealing their true automated nature regardless of their declared User-Agent.
|
|
39
|
+
|
|
40
|
+
### 4. π§ Stateful Behavioral Entropy & Click Variance: Distinguish Humans from Robots
|
|
41
|
+
* **Problem**: Bots can simulate basic interactions, but they lack the subtle, natural imperfections of human behavior, making them hard to differentiate from real users.
|
|
42
|
+
* **Solution**: We analyze real-time user interactions, including mouse movements (speed, acceleration, straightness), typing rhythm (keystroke latency, dwell, and flight times), and click precision (coordinate variance). These metrics reveal whether an interaction is genuinely human or robotically precise.
|
|
43
|
+
* **Benefit**: Identify and block sophisticated bots that attempt to mimic human behavior, protecting your applications from automated fraud, account takeovers, and content manipulation.
|
|
44
|
+
|
|
45
|
+
### 5. π Cross-Layer & Analog Inconsistency Scoring: Expose Advanced Spoofing
|
|
46
|
+
* **Problem**: Bots often try to fake their identity across different layers of their connection, leading to inconsistencies that traditional security systems miss.
|
|
47
|
+
* **Solution**: Our engine cross-references information from various layers (User-Agent, Client Hints, TLS, TCP stack) to detect subtle discrepancies. For example, a client claiming to be a Windows browser but exhibiting a Linux TCP stack will be flagged.
|
|
48
|
+
* **Benefit**: Catch advanced spoofing attempts that bypass single-layer detection, providing a more robust defense against sophisticated attackers.
|
|
49
|
+
|
|
50
|
+
### 6. π Federated Threat Intelligence & Peer Sharing: Immunize Your Network Instantly
|
|
51
|
+
* **Problem**: Isolated servers are vulnerable to distributed attacks, learning about new malicious actors only after being hit and compromised.
|
|
52
|
+
* **Solution**: Our decentralized gossip protocol securely synchronizes cryptographically signed, privacy-compliant threat intelligence (ZKP public keys) with trusted peer networks in real-time. If an attacker is blocked on one federated node, they are instantly blacklisted across all nodes.
|
|
53
|
+
* **Benefit**: Leverage collective defense. Your system is immunized against active botnets before they even attempt to target your servers.
|
|
54
|
+
|
|
55
|
+
### 7. πΈοΈ Coordinated Botnet Clustering: Neutralize IP-Rotation Tactics
|
|
56
|
+
* **Problem**: Modern botnets rotate thousands of clean, residential proxy IPs to easily bypass traditional IP-based reputation lists and standard rate limiters.
|
|
57
|
+
* **Solution**: The engine clusters and profiles incoming requests using highly stable, non-volatile hardware invariants (such as combinations of JA3/JA4, TCP, and GPU hashes). Multiple requests sharing the exact same hardware footprint across distinct IPs within a rolling window are grouped and treated as a single coordinated botnet.
|
|
58
|
+
* **Benefit**: Defeat distributed scraping and credential stuffing campaigns, making expensive residential proxy rotation completely useless for attackers.
|
|
59
|
+
|
|
60
|
+
### 8. π¦ Honeypot Traps & Extensible WAF: Instantly Condemn Malicious Actors
|
|
61
|
+
* **Problem**: Malicious bots and vulnerability scanners often probe for hidden fields or sensitive URLs, but traditional defenses only react after an attack has occurred.
|
|
62
|
+
* **Solution**: We deploy invisible traps (hidden form fields, signed trap URLs) that only bots interact with. Any interaction with these honeypots immediately triggers a maximum suspicion score, leading to instant blocking. Our extensible WAF also detects common injection attempts (SQLi, XSS, RCE).
|
|
63
|
+
* **Benefit**: Proactively identify and block malicious actors at the earliest stage of their attack, preventing data breaches, spam, and system exploitation.
|
|
64
|
+
### 9. 𧬠Progressive Threshold Auto-Tuning: Adapt Your Defenses Automatically
|
|
65
|
+
* **Problem**: Threat landscapes constantly evolve, requiring continuous manual adjustments to security settings, which is time-consuming and prone to human error.
|
|
66
|
+
* **Solution**: Our engine uses a genetic algorithm to continuously optimize your security parameters (weights, thresholds, patterns) in the background, based on real-world traffic data. It learns to distinguish between legitimate users and bots, adapting your defenses in real-time.
|
|
67
|
+
* **Benefit**: Maintain optimal protection without constant manual intervention. Your security posture automatically adapts to new threats and traffic patterns, ensuring maximum effectiveness and minimal false positives.
|
|
68
|
+
|
|
69
|
+
## Quick Start
|
|
70
|
+
|
|
71
|
+
### Node.js
|
|
72
|
+
|
|
73
|
+
```bash
|
|
74
|
+
npm install @anonympins/fingerprint
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
### PHP
|
|
78
|
+
|
|
79
|
+
```bash
|
|
80
|
+
composer require anonympins/fingerprint
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
### Python
|
|
84
|
+
```bash
|
|
85
|
+
pip install fingerprint-engine
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
## Documentation
|
|
89
|
+
|
|
90
|
+
To prevent documentation drift, all detailed guides and reference materials are maintained in the `doc/` directory. Please refer to [these resources](https://github.com/anonympins/fingerprint/wiki/home) to configure and integrate the engine:
|
|
91
|
+
|
|
92
|
+
1. **[Key Concepts & Suspicion Vectors](https://github.com/anonympins/fingerprint/wiki/concepts)**: Learn how the engine calculates suspicion scores across the 15 distinct vectors and manages the Proof-of-Work mitigation layers.
|
|
93
|
+
2. **[Node.js Integration Guide](https://github.com/anonympins/fingerprint/wiki/nodejs_integration)**: Step-by-step instructions for Express.js middleware and raw HTTP server integrations.
|
|
94
|
+
3. **[PHP Integration Guide](https://github.com/anonympins/fingerprint/wiki/php_integration)**: Configuration details for direct PHP integration, TLS fingerprinting forwarding via Nginx/Apache, and securing Prometheus metrics.
|
|
95
|
+
4. **[Python Integration Guide](https://github.com/anonympins/fingerprint/wiki/python_integration)**: Python middleware for ASGI and WSGI integration.
|
|
96
|
+
5. **[Java Integration Guide](https://github.com/anonympins/fingerprint/wiki/java_integration)**: Java library (Servlet, Spring WebFlux)
|
|
97
|
+
6. **[Full Configuration Options](https://github.com/anonympins/fingerprint/wiki/full_options)**: Complete parameter list for fine-tuning weights, custom honeypots, and security profile overrides.
|
|
98
|
+
7. **[API Reference](https://github.com/anonympins/fingerprint/wiki/api_reference)**: Public API signatures and guides on substituting the in-memory datastore with Redis or MongoDB.
|
|
99
|
+
|
|
100
|
+
Start with the **[Documentation Portal](https://github.com/anonympins/fingerprint/wiki/home)** for a complete index.
|
|
101
|
+
|
|
102
|
+
## Contributing
|
|
103
|
+
|
|
104
|
+
We welcome community contributions! Please read our **[Contributing Guidelines](https://github.com/anonympins/fingerprint/blob/main/CONTRIBUTING.md)** for information on:
|
|
105
|
+
- Setting up your local environment (Node.js and PHP).
|
|
106
|
+
- Running the test suites (`Vitest` and `PHPUnit`).
|
|
107
|
+
- Coding and pull request standards.
|
|
108
|
+
|
|
109
|
+
Thanks to our contributors :
|
|
110
|
+
- [anonympins](https://github.com/anonympins)
|
|
111
|
+
|
|
112
|
+
## π Sponsor This Project
|
|
113
|
+
|
|
114
|
+
If this security suite helps protect your business against botnets, automated scraping, credential stuffing, or Layer 7 DDoS attacks, please consider supporting its active development!
|
|
115
|
+
|
|
116
|
+
Sponsorship helps maintain the library, fund active updates, and keep the dynamic WebAssembly engine cutting-edge.
|
|
117
|
+
|
|
118
|
+
**Want to be featured here?** You can also become a sponsor and get your logo displayed in this section simply by running Fingerprint in production on your platforms!
|
|
119
|
+
|
|
120
|
+
### π Featured Sponsors
|
|
121
|
+
|
|
122
|
+
<img src="https://s6.imgcdn.dev/YJTWv9.png" width="100" alt="YJTWv9.png" border="0" valign="middle">
|
|
123
|
+
|
|
124
|
+
[https://primals.net](https://primals.net) and sub-sites
|
|
125
|
+
|
|
126
|
+
|
|
127
|
+
## License
|
|
128
|
+
|
|
120
129
|
This project is licensed under the MIT License.
|
package/composer.json
CHANGED
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@anonympins/fingerprint",
|
|
3
|
-
"version": "0.6.
|
|
3
|
+
"version": "0.6.4",
|
|
4
4
|
"description": "Advanced anti-bot library for Node.js using multi-layer fingerprinting (JA3, client-side, headers), behavioral analysis, and adaptive Proof-of-Work (PoW) challenges to mitigate scraping, scalping, and automated threats.",
|
|
5
5
|
"main": "index.js",
|
|
6
6
|
"type": "module",
|