View Source User Manual
introduction
Introduction
Welcome to the Paraxial.io user manual. This document focuses on using Paraxial.io to effectively block malicious traffic to a site, and requires you to first install the Paraxial.io agent.
index
Index
Definitions
Creating a New Site
The Overview Page
Defining Rules
Rule Events
Allow/Block List
HTTP Traffic
Site Settings
FAQ
1-definitions
1. Definitions
Site - An Elixir/Phoenix/Plug web application that has the Paraxial agent installed and running. You create a site through the Paraxial web interface, provide the site API key to the Paraxial agent, and a connection is established between the Paraxial server and your application. A site has many rules, allowed IP addresses, banned IP address, and site members.
Rule - A user defined condition such as, "If one IP address sends > 20 POST requests to /users/log_in
in a period of 5 seconds, create an alert and ban the IP address." A benefit of Paraxial over traditional systems is that if an IP sending hundreds of requests per second, it will only be permitted to send 20 requests, the 21st will be banned. Compare this with a periodic database query, which would allow hundreds of requests before banning the client.
Rule Event - When an IP address matches a rule, such as, "If an IP sends > 20 POST requests to /users/log_in
in a period of 5 seconds, alert and ban", a rule event is created. The rule event contains information about what caused the rule to be triggered.
Allow List - A list of IP prefixes defined by the user. If an IP matches a prefix on this list, it will always be allowed through. Supports IPv4 and IPv6 prefixes.
Ban List - Similar to Allow List, matching requests will never succeed. Supports IPv4 and IPv6 prefixes.
Site Admin - Has full control over the site.
Site User - Limited control over a site, for example this user cannot delete the site.
2-creating-a-new-site
2. Creating a New Site
When you first create a site, select an appropriate name and timezone. Navigate to "Site Settings", and note the site API key. You will use it to install the Paraxial agent.
3-the-overview-page
3. The Overview Page
The Paraxial.io overview page shows several interesting facts about your site, including:
- Allowed and blocked requests
- Total IP addresses
- Hourly and daily charts
Click the "7 Days" link in the upper right hand corner to switch to the week view.
4-defining-rules
4. Defining Rules
Paraxial.io allows users to define "Rules", which are conditions in their web application related to incoming HTTP traffic. The following are examples of rules:
If an IP sends > 5 POST requests to /accounts/new_user in a 20 second period, create an alert.
If an IP sends > 10 requests of any HTTP method to /projects/*/export in a 12 second period, create an alert and ban the IP address.
If an IP sends > 100 requests of any HTTP method to any path in a 5 second period, ban the IP address.
The purpose of defining rules is to prevent a malicious client from sending an excessive number of unwanted requests. Some examples of requests that you may want to throttle may be related to:
- Login attempts
- New account creation
- Credit card transactions
- Email sending
- Expensive computation
- Excessive total requests (scraping, vulnerability scanning)
- Denial of service attacks
the-rule-creation-form
The Rule Creation Form:
To create a rule, navigate to:
app.paraxial.io/site/:your_site/new_rule
You should see a form that says Create new rule for :your_site
, with some fields. These are:
Rule name
- A user provided string, it should be a descriptive comment on what the rule intends to do.N requests
- The number of requests one IP address can make in the given time period before matching the rule.Time period in seconds
- If you wish to limit login requests to 10 every 5 seconds, this value should be 5.Path
- The path of the incoming request. Uses a custom pattern matching language detailed below.HTTP Methods
- Examples include GET, PUT, POST. Uses a custom pattern matching language detailed below.On trigger
- When the rule is matched, you may create an alert, ban the IP, or do both.
example-rule-creation
Example Rule Creation
To create the rule If an IP sends > 5 POST requests to /accounts/new_user in a 20 second period, create an alert and ban the IP address
, the following form values are used:
Rule name
- This is an arbitrary value, written to be understood by users of Paraxial.io. You could name this "Alert and ban on excessive logins in short period", or "ATO > 5 in 20s to /accounts/new_user". The behavior of the rule is independent of this string, similar to comments in a programming language.N requests
-5
Time period in seconds
-20
Path
-/accounts/new_user
- This must be entered exactly as provided here. If your value does not start with a/
, it will be rejected. More details are below on how path matching works.HTTP Methods
-POST
- This must be entered exactly as provided here. More details on http method matching below.On trigger
-Create an alert and ban the IP
field-details
Field Details
N requests
N requests
must be > 0 and < 999.
Time period in seconds
Time period in seconds
must be > 0 and < 86,400.
Path
The "Path" field uses a custom language for matching on paths. Examples are:
Path *
- Match any path.
Matching:
paraxial.io/new_user
paraxial.io/site/paraxial.io/settings
paraxial.io/site/paraxial.io/edit_users/update
Path /new_user
- Only matching incoming requests for the route new_user
.
Matching:
paraxial.io/new_user
paraxial.io/new_user/
paraxial.io/new_user//
paraxial.io/new_user///
Will not match:
paraxial.io/new_user/a/new_user
paraxial.io/new_user/!
paraxial.io/new_user/a
Path /site/*/settings
- Matching incoming requests for the route /site/:any_value/settings
.
Matching:
paraxial.io/site/paraxial.io/settings
paraxial.io/site/paraxial.io/settings/
paraxial.io/site/customsitehere.com/settings
paraxial.io/site/customsitehere.com/settings/
Will not match:
paraxial.io/site/paraxial.io
paraxial.io/site/paraxial.io/settings/edit_users
Path /site/*/settings/*
- Matching incoming requests for the route /site/:any_value/settings/:any_value
.
Matching:
paraxial.io/site/paraxial.io/edit_users
paraxial.io/site/paraxial.io/list_users
Will not match:
paraxial.io/site/paraxial.io/edit_users/update
paraxial.io/site/paraxial.io
HTTP Methods
The HTTP Methods
field takes a list of comma separated HTTP method names, such as:
GET, POST, PUT
for use in rule matching. It also supports the wildcard *
character, to match all HTTP methods. These are:
GET, HEAD, POST, PUT, DELETE, CONNECT, OPTIONS, TRACE, PATCH
To match all HTTP methods, input: *
To match GET only, input: GET
To match GET and POST, input: GET, POST
To match GET, POST, and PUT, input: GET, POST, PUT
On Trigger
There are three options for On Trigger
:
- Create alert and ban the IP
- Only alert, do not ban
- Only ban, do not alert
5-rule-events
5. Rule Events
The rule events page lists useful information about why an IP address matched a rule. This includes:
- The rule that was matched
- How many requests the IP sent in the rule time period
- If the IP is currently on the allow or ban lists
- Associated login attempts from the IP, if
paraxial_login_user_name
andparaxial_login_success
assigns are in use by your application - The matching HTTP requests, with timestamps
6-allow-block-list
6. Allow/Block List
The IP block and allow lists support IPv4 and IPv6 prefixes. Examples include:
3.5.140.0/22
2600:1f14:fff:f800::/56
7-http-traffic
7. HTTP Traffic
This page displays the most recent 1,000 HTTP events for your site. For each request, you can see:
- IP Address
- HTTP method
- Path requested
- Status code (200, 404, etc.)
- Currently logged in user, if
paraxial_current_user
assigns is used - User Agent
- If the request was allowed
- IP Class, set if the IP matches a cloud provider (AWS, GCP, etc.)
- Timestamp
8-site-settings
8. Site Settings
Current settings are:
- Change site timezone
- Delete site (and all associated site data)
9-faq
9. FAQ
how-long-is-my-site-s-data-stored
How long is my site's data stored?
Seven days, after which it is automatically deleted.
what-is-an-alert-for-a-rule
What is an alert for a rule?
An alert for a rule will be an email or slack message alerting you the rule was matched. This feature is currently in development.
can-i-invite-people-to-be-members-of-my-site
Can I invite people to be members of my site?
This feature is coming soon.