You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/platforms/core.md
+40-33Lines changed: 40 additions & 33 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,37 +4,11 @@ sidebar_position: 2
4
4
5
5
# Core
6
6
7
-
IronShield Core serves as the **intelligence center** of your security infrastructure, providing advanced bot detection, behavioral analysis, and centralized threat coordination across all protection layers.
7
+
IronShield Core is the intelligence center of IronShield security infrastructure. It generates, verifyies, and authenticates **adaptive proof of work challenges**. It also provides advanced bot detection, behavioral analysis, and fingerprinting.
8
8
9
9
## Overview
10
10
11
-
The Core platform operates as the brain of IronShield's security ecosystem, analyzing patterns across multiple data sources to identify sophisticated threats that traditional rule-based systems miss. It employs machine learning algorithms and behavioral fingerprinting to distinguish between human users and automated attacks.
12
-
13
-
### Key Features
14
-
15
-
-**Advanced Bot Detection** - Multi-layered bot identification using behavioral analysis
16
-
-**Stateless Fingerprinting** - Device and browser fingerprinting without persistent storage
17
-
-**Machine Learning Engine** - Adaptive threat detection that improves over time
18
-
-**Behavioral Analysis** - Real-time user behavior profiling and anomaly detection
19
-
-**Threat Intelligence** - Integration with global threat feeds and reputation databases
20
-
21
-
## Architecture
22
-
23
-
```mermaid
24
-
graph TD
25
-
A[Edge Layer] --> B[Core Processing Engine]
26
-
C[API Layer] --> B
27
-
B --> D[Bot Detection Module]
28
-
B --> E[Behavioral Analysis]
29
-
B --> F[ML Threat Engine]
30
-
D --> G[Decision Engine]
31
-
E --> G
32
-
F --> G
33
-
G --> H[Protection Response]
34
-
I[Threat Intelligence] --> F
35
-
```
36
-
37
-
## Getting Started
11
+
The Core platform functions as the primary gatekeeper in front of protected services. Any incoming request to a protected service must solve a proof-of-work computational challenge described in detail below. After successful completion of the challenge, it forwards the incoming traffic to the protected service. Since IronShield challenges are adaptive, the privacy-preserving fingerprinting engine can serve much more difficult challenges to traffic it sees as malicious, such as automated AI-driven scrapers or DDoS attacks, effectively blocking them.
38
12
39
13
40
14
## Understanding Proof of Work Verification
@@ -46,15 +20,48 @@ Before diving into the technical implementation, it's important to understand **
46
20
**Proof of Work** is a cryptographic mechanism that requires a client to perform a computationally expensive operation to prove they have expended real computational resources, most famously implemented in Bitcoin mining. IronShield's similar protocol consists of the following:
47
21
48
22
-**Challenge**: IronShield provides a mathematical puzzle that requires significant CPU cycles to solve. The "work" is the energy expended a device needs to solve the challenge.
49
-
-**Solution**: The client must find a specific value (usually called a "nonce") that, when combined with the provided challenge data, produces a cryptographic hash with certain properties.
23
+
-**Solution**: The client must find a specific value (usually called a "nonce") that, when combined with the provided challenge data, produces a cryptographic hash (e.g. SHA-256) with certain properties.
50
24
-**Verification**: Any independent party can easily and quickly verify the solution is correct without having to recompute the soluition from scratch, but can be certain that the solver initially found it utilizing substantial computational work.
51
25
52
-
53
-
54
26
### Why PoW Stops Bad Actors
55
-
The problem with traditional automated attacks (bots, scrapers, DDoS) is that anybody with 20 minutes of effort and 50 dollars can bring a multimillion dollar system offline because spamming endpoints is incredibly cheap to do yet extremly costly to defend againt.
27
+
The problem with traditional automated attacks (bots, scrapers, DDoS) is that anybody with 20 minutes of effort and 50 dollars can bring a multi-million dollar system offline because spamming endpoints is incredibly cheap to do yet extremly costly to defend againt.
28
+
29
+
IronShield Core turns scraping and DDoS protection from a networking problem to an economic one. Attacks become economically unfeasible when each request requires significant computational cost. Malicious actors can't easily scale attacks because each request demands real CPU time and energy consumption to the point where the assymetric cost IronShield creates would make an attack economically infeasible. On the other hand, the "cost" to real users solving occasional challenges is imperceptible since they only have to solve one challenge and can use all of their computer's hardware to do so for free.
30
+
31
+
## How IronSHield's PoW Functions
32
+
33
+
### Step 1: Client Decodes a Challenge
34
+
IronShield's protocol primarily communicates with HTTP headers, for more infomration see the [API Platform Documentation](/docs/platforms/api).
IronShield Core turns scraping and DDoS protection from a networking problem to an economic one. Attacks become economically unfeasible when each request requires significant computational cost. Malicious actors can't easily scale attacks because each request demands real CPU time and energy consumption. On the other hand, the "cost" to real users solving occasional challenges is imperceptible since they only have to solve one challenge and can use all of their computer's hardware to do so for free.
50
+
### The Computational Challenge
51
+
To solve an `IronShieldChallenge`, a client must find some `solution` nonce that when concatenated with the `random_nonce`, and the resulting string is hashed with SHA-256, such that the resulting hash represented as a *[u8; 32] little-endian byte array* is smaller than the `challenge_param` target threshold byte array. The lower the `challenge_param` is, the harder the challenge is. For example, the average probability of finding a SHA-256 hash less than 2^255 represented as a [u8; 32] byte array ([0, 0, 0, ..., 128]) is 50% since there is a 50% chance any random integer chosen between 0 and 2^256 will be less than 2^255. Mathematically, the probability of solving a given challenge is `challenge_param / 2^256`. Therefore, the difficulty, or the expected average number of attempts to solve a challenge, is `2^256 / challenge_param`.
52
+
53
+
#### Random Nonce
54
+
The `random_nonce` is a SHA-256 hash of a random number represented as a hex string generated by IronShield servers. Since clients have to find a valid nonce that concatenated w
55
+
**What Each Field Means:**
56
+
57
+
-**`random_nonce`**: The SHA-256 hash of a random number (hex string)
58
+
-**`created_time`**: Unix milli timestamp for the challenge.
59
+
-**`expiration_time`**: Unix milli timestamp for the challenge expiration time.
60
+
-**`challenge_param`**: Target threshold - hash must be less than this value.
61
+
-**`recommended_attempts`**: Expected number of attempts for user guidance (2x difficulty).
62
+
-**`website_id`**: The identifier of the website.
63
+
-**`public_key`**: Ed25519 public key for signature verification.
64
+
-**`challenge_signature`**: Ed25519 signature over the challenge data.
0 commit comments