Sproxy is a real proxy, it captures the requests (all supported types by the Spring framework) and forwards them to the requested url, applying different types of modifications.
Supported HTTP methods are:
- GET
- HEAD
- POST
- DELETE
- OPTIONS
- PATCH
- PUT
It is possible to specify the protocol, for instance specifying HTTP
http://localhost:8080/http://postman-echo.com/get?foo1=bar1
Or HTTPS
http://localhost:8080/https://postman-echo.com/get?foo1=bar1
When there is no protocol Sproxy will try to forward the request, to the requested URL, using HTTPS first;
If the operation will fail Sproxy will use the HTTP
http://localhost:8080/postman-echo.com/get?foo1=bar1
In the same way is possible using directly an IP address
localhost:8080/52.73.240.226/get?foo1=bar1
or
localhost:8080/https://52.73.240.226/get?foo1=bar1
The port can also be specified directly in the request
http://localhost:8080/postman-echo.com:80/get?foo1=bar1
http://localhost:8080/postman-echo.com:443/get?foo1=bar1
The url can be customized in a lot of different ways, Sproxy will try to understand where to send the request and which parameters should be used.
Sproxy provides different features to enable some extras.
Available features:
- FEATURE TLS
- With this feature you will be able to set up TLS. Sproxy starts on port 8080 by default but enabling TLS it will
start on port 8443.
You can also set up *the http to https redirection, just assigningtrue
to thehttp-to-https
property in the configuration file.
Supported keystore (how to create a keystore is out of scope but search on google, you will find how to do it) types are:- PKCS12
- JKS
- With this feature you will be able to set up TLS. Sproxy starts on port 8080 by default but enabling TLS it will
start on port 8443.
The http to https redirection will redirect ALWAYS using ONLY the GET http verb.
F.I. if you try to call Sproxy using the POST verb you'll notice a correct redirection but as result the proxied method
will be ALWAYS a GET (the proxied server will receive a GET request).
Why?
Essentially because if you are making a redirection from http to https using POST or another verb you are sending
sensitive data through an insecure channel, so it just doesn't make sense to do that. This would be a vulnerability.
This is not an invention, it is a guideline! So if you are using redirection you will be forced to give the https url to
the clients, for verbs != GET, in order to establish the connection on a secure channel.
With Sproxy is also possible using "mods".
Available mods:
- MOD HEADERS
- Thanks to this mod it is possible to modify both request and response headers.
- MOD URL
- This mod permits to define a whitelist and a blacklist to grant or deny the destination urls that Sproxy will be able to reach.
- MOD SECURITY
- This mod is still not available... interesting features about session management and authentication will be added.
- MOD WAF
- Through this mode Sproxy is able to enable the Spring's built-in StrictHttpFirewall.
Because Sproxy provides several levels of security and conveniences!
You could use it as a transparent proxy but enabling extra features.
It can be extremely useful when you need to resolve CORS related issues or more generally when you need to modify both
request or response headers.
If you need to enable https for your endpoints you could simply enable https on Sproxy and he will take care of
transporting traffic to others services in http reporting the responses to the client using https.
It's useful when you need to restrict the access for specific urls, you can do it by using the MOD URL, mixing
white-listing and black-listing.
Improve security making Sproxy acts as a Web Application Firewall, it uses the powerful built-in Spring Boot
StrictHttpFirewall.
Others interesting features like session management and users authentication are coming, it will be possible to assign
users credentials in order to restrict the access using both Bearer and Basic authentication.
Project Sproxy is strictly connected to docker in order to retrace the java WORA (Write Once Run Anywhere) concept with extreme simplicity and portability. So if you want to run it out of the docker context (it's possible too) you are free to do it but you'll not find any useful information about configuration or other stuff here.
Here's a minimal docker compose file (is everything you need) useful to run Sproxy:
docker-compose.yaml
version: "3.8"
services:
sproxy:
container_name: sproxy
image: robertoman/sproxy:latest
ports:
- 80:8080 #(if FEATURE TLS is disabled) or (if FEATURE TLS is enabled && http-to-https == true)
- 443:8443 #(if FEATURE TLS is enabled)
volumes:
- ./config:/config
- ./logs:/var/log/sproxy
environment:
- spring.profiles.active=default,eureka #(if eureka is enabled)
Here's the recommended directory structure
- sproxy
|
+file----> docker-compose.yaml
|
+folder--> config
| |
| +file--> application.yaml
| |
| +file--> application-eureka.yaml #(if eureka is enabled)
| |
| +file--> keystore.p12 #(if FEATURE TLS is enabled)
|
+folder--> logs
|
+file--> sproxy.log #(autogenerated at startup)
So after this you can simply run docker-compose up -d
(at the same level of docker-compose.yaml) to start Sproxy.
Sproxy comes with a default properties file, shipped within the jar. If you want to inspect the default properties you
should give a look at the application.yaml
here:
https://github.com/robertomanfreda/sproxy/blob/master/src/main/resources/application.yaml
Anyway it is not recommended using the default file, you should provide an external configuration to customize the
sproxy mods and all other features like TLS and so on. Create the file and place it in the /config
folder
(explained below).
Accepted names for the configuration file are:
- application.yaml
- application.yml
- application.properties
Eventually additional configuration files can be add, but if you do that you need to explicitly define spring active profiles through the docker-compose.
Here's a complete example of configuration file:
application-sproxy.yaml
logging:
level:
com.robertoman.sproxy: debug
config:
show-homepage: true
feature:
#---------- FEATURE TLS ----------#
tls:
enabled: true
http-to-https: true
key-alias: alias
key-store-password: password
key-store: '/config/keystore.p12'
key-store-type: PKCS12
mod:
#---------- MOD HEADERS ----------#
headers:
enabled: true
request:
allow-overrides: true
map:
# WARNING: the indentation is important, here's we are declaring a Map<String, List<String>>
(https?://)?postman-echo.com/.*+:
- 'Foo: bar'
- 'Bat: baz'
- 'Another-Custom-Header: custom'
(https?://)?(www.)?google.(com|it)(/.*)?:
- 'An-Header: 1'
- 'Another-Header: 2'
response:
allow-overrides: false
# WARING: just use '{}' if you don't have any value to specify or the startup will fail
map: {}
#---------- MOD URL ----------#
url:
enabled: true
whitelist:
- '(https?://)?postman-echo.com/.*+'
- '(https?://)?yoursite.org((/)?.*+)?'
blacklist:
- '(https?://)?www.google.com'
- '(https?://)?(www.)?evilsite.(com|org|net)((/)?.*+)?'
#---------- MOD WAF ----------#
waf:
enabled: true
allows:
backslash: false
url-encoded-double-slash: true
url-uncoded-percent: false
url-encoded-period: false
url-encoded-slash: false
semicolon: false
host-names:
- localhost
- example.com
http-methods:
- GET
- HEAD
- POST
Sproxy supports eureka registration, all dependencies are provided within the jar package.
By default the autodiscovery is disabled.
If you need to enable the discovery client features there are 2 steps to do:
- Create a file named
application-eureka.yaml
and place it into your config folder. - Put in the environment this variable via docker-compose:
spring.profiles.active=default,eureka
Here's an example of application-eureka.yaml:
spring:
application:
name: sproxy
config:
eureka-server:
proto: http
base: localhost
port: 7000
eureka:
client:
enabled: true
service-url:
defaultZone: ${config.eureka-server.proto}://${config.eureka-server.base}:${config.eureka-server.port}/eureka
instance:
hostname: ${spring.application.name}
management:
endpoints:
web:
exposure:
include: '*'
endpoint:
health:
show-details: always
If you don't want to provide any external properties file you can compile Sproxy from sources:
git clone https://github.com/robertomanfreda/sproxy.git
cd sproxy
- modify what you want
mvn -U clean package
docker build -t com.robertoman/sproxy:custom .
docker run -d --name sproxy com.robertoman/sproxy:custom
mapping ports, config folder and logs volumes as you prefer
More content will be added