mirror of
https://github.com/bitechdev/ResolveSpec.git
synced 2026-01-01 17:44:24 +00:00
A lot more tests
This commit is contained in:
Hein
440
pkg/security/SECURITY_FEATURES.md
Normal file
440
pkg/security/SECURITY_FEATURES.md
Normal file
@@ -0,0 +1,440 @@
|
||||
# Security Features: Blacklist & Rate Limit Inspection
|
||||
|
||||
## IP Blacklist
|
||||
|
||||
The IP blacklist middleware allows you to block specific IP addresses or CIDR ranges from accessing your application.
|
||||
|
||||
### Basic Usage
|
||||
|
||||
```go
|
||||
import "github.com/bitechdev/ResolveSpec/pkg/middleware"
|
||||
|
||||
// Create blacklist (UseProxy=true if behind a proxy)
|
||||
blacklist := middleware.NewIPBlacklist(middleware.BlacklistConfig{
|
||||
UseProxy: true, // Checks X-Forwarded-For and X-Real-IP headers
|
||||
})
|
||||
|
||||
// Block individual IP
|
||||
blacklist.BlockIP("192.168.1.100", "Suspicious activity detected")
|
||||
|
||||
// Block entire CIDR range
|
||||
blacklist.BlockCIDR("10.0.0.0/8", "Private network blocked")
|
||||
|
||||
// Apply middleware
|
||||
http.Handle("/api/", blacklist.Middleware(yourHandler))
|
||||
```
|
||||
|
||||
### Managing Blacklist
|
||||
|
||||
```go
|
||||
// Unblock an IP
|
||||
blacklist.UnblockIP("192.168.1.100")
|
||||
|
||||
// Unblock a CIDR range
|
||||
blacklist.UnblockCIDR("10.0.0.0/8")
|
||||
|
||||
// Get all blacklisted IPs and CIDRs
|
||||
ips, cidrs := blacklist.GetBlacklist()
|
||||
fmt.Printf("Blocked IPs: %v\n", ips)
|
||||
fmt.Printf("Blocked CIDRs: %v\n", cidrs)
|
||||
|
||||
// Check if specific IP is blocked
|
||||
blocked, reason := blacklist.IsBlocked("192.168.1.100")
|
||||
if blocked {
|
||||
fmt.Printf("IP blocked: %s\n", reason)
|
||||
}
|
||||
```
|
||||
|
||||
### Blacklist Statistics Endpoint
|
||||
|
||||
Expose blacklist statistics via HTTP:
|
||||
|
||||
```go
|
||||
// Add stats endpoint
|
||||
http.Handle("/admin/blacklist-stats", blacklist.StatsHandler())
|
||||
```
|
||||
|
||||
**Example Response:**
|
||||
```json
|
||||
{
|
||||
"blocked_ips": ["192.168.1.100", "192.168.1.101"],
|
||||
"blocked_cidrs": ["10.0.0.0/8"],
|
||||
"total_ips": 2,
|
||||
"total_cidrs": 1
|
||||
}
|
||||
```
|
||||
|
||||
### Integration Example
|
||||
|
||||
```go
|
||||
func main() {
|
||||
// Create blacklist
|
||||
blacklist := middleware.NewIPBlacklist(middleware.BlacklistConfig{
|
||||
UseProxy: true,
|
||||
})
|
||||
|
||||
// Block known malicious IPs
|
||||
blacklist.BlockIP("203.0.113.1", "Known scanner")
|
||||
blacklist.BlockCIDR("198.51.100.0/24", "Spam network")
|
||||
|
||||
// Create your router
|
||||
mux := http.NewServeMux()
|
||||
|
||||
// Protected routes
|
||||
mux.Handle("/api/", blacklist.Middleware(apiHandler))
|
||||
|
||||
// Admin endpoint to manage blacklist
|
||||
mux.HandleFunc("/admin/block-ip", func(w http.ResponseWriter, r *http.Request) {
|
||||
ip := r.URL.Query().Get("ip")
|
||||
reason := r.URL.Query().Get("reason")
|
||||
|
||||
if err := blacklist.BlockIP(ip, reason); err != nil {
|
||||
http.Error(w, err.Error(), http.StatusBadRequest)
|
||||
return
|
||||
}
|
||||
|
||||
w.WriteHeader(http.StatusOK)
|
||||
fmt.Fprintf(w, "Blocked %s: %s", ip, reason)
|
||||
})
|
||||
|
||||
// Stats endpoint
|
||||
mux.Handle("/admin/blacklist-stats", blacklist.StatsHandler())
|
||||
|
||||
http.ListenAndServe(":8080", mux)
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Rate Limit Inspection
|
||||
|
||||
Monitor and inspect rate limit status per IP address in real-time.
|
||||
|
||||
### Basic Usage
|
||||
|
||||
```go
|
||||
import "github.com/bitechdev/ResolveSpec/pkg/middleware"
|
||||
|
||||
// Create rate limiter (10 req/sec, burst of 20)
|
||||
rateLimiter := middleware.NewRateLimiter(10, 20)
|
||||
|
||||
// Apply middleware
|
||||
http.Handle("/api/", rateLimiter.Middleware(yourHandler))
|
||||
```
|
||||
|
||||
### Programmatic Inspection
|
||||
|
||||
```go
|
||||
// Get all tracked IPs
|
||||
trackedIPs := rateLimiter.GetTrackedIPs()
|
||||
fmt.Printf("Currently tracking %d IPs\n", len(trackedIPs))
|
||||
|
||||
// Get rate limit info for specific IP
|
||||
info := rateLimiter.GetRateLimitInfo("192.168.1.1")
|
||||
fmt.Printf("IP: %s\n", info.IP)
|
||||
fmt.Printf("Tokens Remaining: %.2f\n", info.TokensRemaining)
|
||||
fmt.Printf("Limit: %.2f req/sec\n", info.Limit)
|
||||
fmt.Printf("Burst: %d\n", info.Burst)
|
||||
|
||||
// Get info for all tracked IPs
|
||||
allInfo := rateLimiter.GetAllRateLimitInfo()
|
||||
for _, info := range allInfo {
|
||||
fmt.Printf("%s: %.2f tokens remaining\n", info.IP, info.TokensRemaining)
|
||||
}
|
||||
```
|
||||
|
||||
### Rate Limit Stats Endpoint
|
||||
|
||||
Expose rate limit statistics via HTTP:
|
||||
|
||||
```go
|
||||
// Add stats endpoint
|
||||
http.Handle("/admin/rate-limit-stats", rateLimiter.StatsHandler())
|
||||
```
|
||||
|
||||
**Example Response (all IPs):**
|
||||
```json
|
||||
{
|
||||
"total_tracked_ips": 3,
|
||||
"rate_limit_config": {
|
||||
"requests_per_second": 10,
|
||||
"burst": 20
|
||||
},
|
||||
"tracked_ips": [
|
||||
{
|
||||
"ip": "192.168.1.1",
|
||||
"tokens_remaining": 15.5,
|
||||
"limit": 10,
|
||||
"burst": 20
|
||||
},
|
||||
{
|
||||
"ip": "192.168.1.2",
|
||||
"tokens_remaining": 18.2,
|
||||
"limit": 10,
|
||||
"burst": 20
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Example Response (specific IP):**
|
||||
```bash
|
||||
GET /admin/rate-limit-stats?ip=192.168.1.1
|
||||
```
|
||||
```json
|
||||
{
|
||||
"ip": "192.168.1.1",
|
||||
"tokens_remaining": 15.5,
|
||||
"limit": 10,
|
||||
"burst": 20
|
||||
}
|
||||
```
|
||||
|
||||
### Complete Integration Example
|
||||
|
||||
```go
|
||||
package main
|
||||
|
||||
import (
|
||||
"encoding/json"
|
||||
"fmt"
|
||||
"net/http"
|
||||
|
||||
"github.com/bitechdev/ResolveSpec/pkg/middleware"
|
||||
)
|
||||
|
||||
func main() {
|
||||
// Create rate limiter
|
||||
rateLimiter := middleware.NewRateLimiter(10, 20)
|
||||
|
||||
// Create blacklist
|
||||
blacklist := middleware.NewIPBlacklist(middleware.BlacklistConfig{
|
||||
UseProxy: true,
|
||||
})
|
||||
|
||||
mux := http.NewServeMux()
|
||||
|
||||
// API handler with both middlewares (blacklist first, then rate limit)
|
||||
apiHandler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
|
||||
w.WriteHeader(http.StatusOK)
|
||||
json.NewEncoder(w).Encode(map[string]string{
|
||||
"message": "Success",
|
||||
})
|
||||
})
|
||||
|
||||
// Apply middleware chain: blacklist -> rate limit -> handler
|
||||
mux.Handle("/api/", blacklist.Middleware(rateLimiter.Middleware(apiHandler)))
|
||||
|
||||
// Admin endpoints
|
||||
mux.Handle("/admin/rate-limit-stats", rateLimiter.StatsHandler())
|
||||
mux.Handle("/admin/blacklist-stats", blacklist.StatsHandler())
|
||||
|
||||
// Custom monitoring endpoint
|
||||
mux.HandleFunc("/admin/monitor", func(w http.ResponseWriter, r *http.Request) {
|
||||
// Get rate limit stats
|
||||
rateLimitInfo := rateLimiter.GetAllRateLimitInfo()
|
||||
|
||||
// Get blacklist stats
|
||||
blockedIPs, blockedCIDRs := blacklist.GetBlacklist()
|
||||
|
||||
response := map[string]interface{}{
|
||||
"rate_limits": rateLimitInfo,
|
||||
"blacklist": map[string]interface{}{
|
||||
"ips": blockedIPs,
|
||||
"cidrs": blockedCIDRs,
|
||||
},
|
||||
}
|
||||
|
||||
w.Header().Set("Content-Type", "application/json")
|
||||
json.NewEncoder(w).Encode(response)
|
||||
})
|
||||
|
||||
// Dynamic blacklist management
|
||||
mux.HandleFunc("/admin/block", func(w http.ResponseWriter, r *http.Request) {
|
||||
ip := r.URL.Query().Get("ip")
|
||||
reason := r.URL.Query().Get("reason")
|
||||
|
||||
if ip == "" {
|
||||
http.Error(w, "IP required", http.StatusBadRequest)
|
||||
return
|
||||
}
|
||||
|
||||
if err := blacklist.BlockIP(ip, reason); err != nil {
|
||||
http.Error(w, err.Error(), http.StatusBadRequest)
|
||||
return
|
||||
}
|
||||
|
||||
fmt.Fprintf(w, "Blocked %s: %s", ip, reason)
|
||||
})
|
||||
|
||||
mux.HandleFunc("/admin/unblock", func(w http.ResponseWriter, r *http.Request) {
|
||||
ip := r.URL.Query().Get("ip")
|
||||
if ip == "" {
|
||||
http.Error(w, "IP required", http.StatusBadRequest)
|
||||
return
|
||||
}
|
||||
|
||||
blacklist.UnblockIP(ip)
|
||||
fmt.Fprintf(w, "Unblocked %s", ip)
|
||||
})
|
||||
|
||||
// Auto-block IPs that exceed rate limit
|
||||
mux.HandleFunc("/admin/auto-block-heavy-users", func(w http.ResponseWriter, r *http.Request) {
|
||||
blocked := 0
|
||||
|
||||
for _, info := range rateLimiter.GetAllRateLimitInfo() {
|
||||
// If tokens are very low, IP is making many requests
|
||||
if info.TokensRemaining < 1.0 {
|
||||
blacklist.BlockIP(info.IP, "Exceeded rate limit")
|
||||
blocked++
|
||||
}
|
||||
}
|
||||
|
||||
fmt.Fprintf(w, "Blocked %d IPs exceeding rate limits", blocked)
|
||||
})
|
||||
|
||||
fmt.Println("Server starting on :8080")
|
||||
fmt.Println("Rate limit stats: http://localhost:8080/admin/rate-limit-stats")
|
||||
fmt.Println("Blacklist stats: http://localhost:8080/admin/blacklist-stats")
|
||||
http.ListenAndServe(":8080", mux)
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Monitoring Dashboard Example
|
||||
|
||||
Create a simple monitoring page:
|
||||
|
||||
```go
|
||||
mux.HandleFunc("/admin/dashboard", func(w http.ResponseWriter, r *http.Request) {
|
||||
html := `
|
||||
<html>
|
||||
<head>
|
||||
<title>Security Dashboard</title>
|
||||
<script>
|
||||
async function loadStats() {
|
||||
const rateLimitRes = await fetch('/admin/rate-limit-stats');
|
||||
const rateLimitData = await rateLimitRes.json();
|
||||
|
||||
const blacklistRes = await fetch('/admin/blacklist-stats');
|
||||
const blacklistData = await blacklistRes.json();
|
||||
|
||||
document.getElementById('rate-limit').innerHTML =
|
||||
JSON.stringify(rateLimitData, null, 2);
|
||||
document.getElementById('blacklist').innerHTML =
|
||||
JSON.stringify(blacklistData, null, 2);
|
||||
}
|
||||
|
||||
setInterval(loadStats, 5000); // Refresh every 5 seconds
|
||||
loadStats();
|
||||
</script>
|
||||
</head>
|
||||
<body>
|
||||
<h1>Security Dashboard</h1>
|
||||
|
||||
<h2>Rate Limits</h2>
|
||||
<pre id="rate-limit">Loading...</pre>
|
||||
|
||||
<h2>Blacklist</h2>
|
||||
<pre id="blacklist">Loading...</pre>
|
||||
</body>
|
||||
</html>
|
||||
`
|
||||
|
||||
w.Header().Set("Content-Type", "text/html")
|
||||
w.Write([]byte(html))
|
||||
})
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 1. Proxy Configuration
|
||||
Always set `UseProxy: true` when running behind a reverse proxy (nginx, Cloudflare, etc.):
|
||||
```go
|
||||
blacklist := middleware.NewIPBlacklist(middleware.BlacklistConfig{
|
||||
UseProxy: true, // Checks X-Forwarded-For headers
|
||||
})
|
||||
```
|
||||
|
||||
### 2. Middleware Order
|
||||
Apply blacklist before rate limiting to save resources:
|
||||
```go
|
||||
// Correct order: blacklist -> rate limit -> handler
|
||||
handler := blacklist.Middleware(
|
||||
rateLimiter.Middleware(yourHandler)
|
||||
)
|
||||
```
|
||||
|
||||
### 3. Secure Admin Endpoints
|
||||
Protect admin endpoints with authentication:
|
||||
```go
|
||||
mux.Handle("/admin/", authMiddleware(adminHandler))
|
||||
```
|
||||
|
||||
### 4. Monitoring
|
||||
Set up alerts when:
|
||||
- Many IPs are being rate limited
|
||||
- Blacklist grows too large
|
||||
- Specific IPs are repeatedly blocked
|
||||
|
||||
### 5. Dynamic Response
|
||||
Automatically block IPs that consistently exceed rate limits:
|
||||
```go
|
||||
// Check every minute
|
||||
ticker := time.NewTicker(1 * time.Minute)
|
||||
go func() {
|
||||
for range ticker.C {
|
||||
for _, info := range rateLimiter.GetAllRateLimitInfo() {
|
||||
if info.TokensRemaining < 0.5 {
|
||||
blacklist.BlockIP(info.IP, "Automated block: rate limit exceeded")
|
||||
}
|
||||
}
|
||||
}
|
||||
}()
|
||||
```
|
||||
|
||||
### 6. CIDR for Network Blocks
|
||||
Use CIDR ranges to block entire networks efficiently:
|
||||
```go
|
||||
// Block entire subnets
|
||||
blacklist.BlockCIDR("10.0.0.0/8", "Private network")
|
||||
blacklist.BlockCIDR("192.168.0.0/16", "Local network")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## API Reference
|
||||
|
||||
### IPBlacklist
|
||||
|
||||
#### Methods
|
||||
- `BlockIP(ip, reason string) error` - Block a single IP address
|
||||
- `BlockCIDR(cidr, reason string) error` - Block a CIDR range
|
||||
- `UnblockIP(ip string)` - Remove IP from blacklist
|
||||
- `UnblockCIDR(cidr string)` - Remove CIDR from blacklist
|
||||
- `IsBlocked(ip string) (blocked bool, reason string)` - Check if IP is blocked
|
||||
- `GetBlacklist() (ips, cidrs []string)` - Get all blocked IPs and CIDRs
|
||||
- `Middleware(next http.Handler) http.Handler` - HTTP middleware
|
||||
- `StatsHandler() http.Handler` - HTTP handler for statistics
|
||||
|
||||
### RateLimiter
|
||||
|
||||
#### Methods
|
||||
- `GetTrackedIPs() []string` - Get all tracked IP addresses
|
||||
- `GetRateLimitInfo(ip string) *RateLimitInfo` - Get info for specific IP
|
||||
- `GetAllRateLimitInfo() []*RateLimitInfo` - Get info for all tracked IPs
|
||||
- `Middleware(next http.Handler) http.Handler` - HTTP middleware
|
||||
- `StatsHandler() http.Handler` - HTTP handler for statistics
|
||||
|
||||
#### RateLimitInfo Structure
|
||||
```go
|
||||
type RateLimitInfo struct {
|
||||
IP string `json:"ip"`
|
||||
TokensRemaining float64 `json:"tokens_remaining"`
|
||||
Limit float64 `json:"limit"`
|
||||
Burst int `json:"burst"`
|
||||
}
|
||||
```
|
||||
Reference in New Issue
Block a user