Powershell/cybersecurity/Network Reputation Service/readme-en.md

# 🛡️ Firewall Audit - Network Reputation Service

![Version](https://img.shields.io/badge/version-1.3-blue.svg)
![PowerShell](https://img.shields.io/badge/PowerShell-5.1+-blue.svg)
![License](https://img.shields.io/badge/license-MIT-green.svg)

A professional PowerShell audit tool to evaluate your firewall's filtering effectiveness by testing categorized URLs based on their network reputation.

## 📋 Table of Contents

- [Overview](#-overview)
- [Features](#-features)
- [Prerequisites](#-prerequisites)
- [Installation](#-installation)
- [Usage](#-usage)
- [Configuration](#-configuration)
- [Generated Report](#-generated-report)
- [Data Structure](#-data-structure)
- [Scoring System](#-scoring-system)
- [Troubleshooting](#-troubleshooting)
- [Contributing](#-contributing)
- [License](#-license)

## 🎯 Overview

This PowerShell script tests your firewall's effectiveness by verifying that malicious URLs are correctly blocked while legitimate sites remain accessible. It generates a professional HTML report with scoring, statistics, and recommendations.

**Author:** Hubert Cornet  
**Version:** 1.3  
**Date:** September 3, 2025

## ✨ Features

- 🔍 **Automated testing** of hundreds of categorized URLs
- 📊 **Smart scoring** with grades from A+ to F
- 📱 **Responsive HTML report** with interactive interface
- 🔧 **Proxy support** with authentication
- ⚡ **Real-time progress bars**
- 🎨 **Color-coded visualizations** of results
- 💾 **JSON export** of raw data
- 🌐 **Multi-method detection** of blocks

## 📋 Prerequisites

### System Requirements
- Windows 10/11 or Windows Server 2016+
- PowerShell 5.1 or higher
- Active Internet connection
- Write permissions in the script directory

### PowerShell Modules (installed automatically)
- `PSWriteHTML`
- `PSWriteColor`

### Required Files
- `file-nrs.json` - Categorized URLs database

## 🚀 Installation

1. **Download the script** to a dedicated folder
2. **Download the JSON file** from:
   ```
   https://gitea.tips-of-mine.com/Tips-Of-Mine/Powershell/src/branch/main/cybersecurity/Network%20Reputation%20Service/file-nrs.json
   ```
3. **Place both files** in the same directory

## 💻 Usage

### Basic Usage
```powershell
.\AuditFirewall.ps1
```

### With Proxy
```powershell
.\AuditFirewall.ps1 -ProxyUrl "http://proxy.company.com:8080"
```

### With Proxy Authentication
```powershell
.\AuditFirewall.ps1 -ProxyUrl "http://proxy.company.com:8080" -ProxyUseAuthentication
```

### With Custom Timeout
```powershell
.\AuditFirewall.ps1 -TimeoutSeconds 15
```

## ⚙️ Configuration

### Available Parameters

| Parameter | Type | Description | Default |
|-----------|------|-------------|---------|
| `ProxyUrl` | String | Network proxy URL | None |
| `ProxyUseAuthentication` | Switch | Enable proxy auth | False |
| `TimeoutSeconds` | Integer | Timeout per URL | 10 |

### Customizing Block Keywords
Modify the `$BlockKeywords` variable in the script:
```powershell
$BlockKeywords = @("site blocked", "access denied", "web filtering", "Access Denied", "Site Blocked")
```

## 📊 Generated Report

The script automatically generates:

### 📁 Output File Structure
```
Reports/
└── [Date and Time]/
    ├── Audit_Firewall_Report.html    # Main report
    └── Results.json                   # Raw data
```

### 🎨 HTML Report Content
- **Executive Summary**: Global score and key statistics
- **Score Table**: Performance by category
- **Interactive Details**: Individual tests by URL
- **Grading Scale**: Scoring system explanation

## 📁 Data Structure

### `file-nrs.json` Format
```json
{
  "categorie": [
    {
      "id": "malware",
      "nom": "Malware",
      "description": "Sites distributing malicious software",
      "urls": [
        {
          "url": "http://example-malware.com",
          "reputation": "malicious",
          "expected_action": "block"
        },
        {
          "url": "https://legitimate-site.com",
          "reputation": "safe",
          "expected_action": "allow"
        }
      ]
    }
  ]
}
```

### Expected Actions
- `"block"`: URL should be blocked by firewall
- `"allow"`: URL should remain accessible

## 📈 Scoring System

### Grading Scale

| Grade | Score | Interpretation |
|-------|--------|---------------|
| **A+** | 95-100% | 🟢 Excellent / Perfect |
| **A** | 90-95% | 🟢 Very good filtering level |
| **B+** | 85-90% | 🟡 Very good |
| **B** | 80-85% | 🟡 Good, some adjustments needed |
| **C+** | 75-80% | 🟠 Fairly good |
| **C** | 70-75% | 🟠 Average, significant gaps |
| **D+** | 65-70% | 🔴 Acceptable |
| **D** | 60-65% | 🔴 Weak, ineffective filtering |
| **E+** | 55-60% | 🔴 Very weak |
| **E** | 50-55% | 🔴 Insufficient |
| **F+** | 45-50% | ⚫ Critical |
| **F** | 0-45% | ⚫ Immediate action required |

### Calculation Method
```
Score = (Correctly filtered URLs / Total tested URLs) × 100
```

## 🔍 Detection Methods

### How the script detects blocks:
1. **Content Analysis**: Search for block page keywords
2. **Network Timeouts**: Requests that expire (probable firewall block)
3. **Connection Errors**: Unable to reach the server
4. **HTTP Status Codes**: Analysis of server responses

### Simulated HTTP Headers:
The script simulates a modern browser to avoid detection:
```
User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36...
Accept: text/html,application/xhtml+xml,application/xml...
Accept-Language: fr-FR,fr;q=0.9,en-US;q=0.8,en;q=0.7
```

## 🔧 Troubleshooting

### Common Issues

#### ❌ "File 'file-nrs.json' does not exist!"
**Solution:** Download the JSON file from the provided link and place it in the same folder as the script.

#### ❌ "Cannot install module X"
**Solution:** Run PowerShell as administrator or use:
```powershell
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
```

#### ❌ Frequent Timeouts
**Solutions:**
- Increase `-TimeoutSeconds` value
- Check your network connection
- Configure proxy settings correctly

#### ❌ False Positives/Negatives
**Solutions:**
- Update block keywords
- Verify firewall configuration
- Adapt JSON file to your environment

## 🏢 Recommended Use Cases

### 📅 Periodic Usage
- **Monthly audit** of firewall effectiveness
- **Validation** after rule updates
- **Benchmarking** between security solutions

### 👥 Management Reporting
- **Dashboards** for IT management
- **Measurable security KPIs**
- **Investment justification** for security

### 🔧 Configuration Testing
- **Validation** after network changes
- **Regression testing** of firewall rules
- **Security compliance audit**

## ⚠️ Technical Limitations

### Points of Attention:
- **Sequential Testing**: No parallelization (can be slow)
- **Basic Detection**: Relies on predefined keywords
- **False Positives**: Legitimate sites temporarily inaccessible
- **Security**: Script actually contacts tested URLs

### Best Practices:
1. 🕐 Run during off-peak hours
2. 📊 Analyze results in context
3. 🔄 Keep JSON file updated
4. 📈 Track score evolution over time

## 🤝 Contributing

### To Contribute:
1. Fork the project
2. Create your feature branch
3. Commit your changes
4. Push to the branch
5. Open a Pull Request

### Improvement Ideas:
- [ ] Test parallelization for better performance
- [ ] More sophisticated block page detection
- [ ] External reputation database support
- [ ] Graphical interface for configuration
- [ ] Threat intelligence API integration

## 🎯 Roadmap

### Version 1.4 (planned)
- [ ] Parallel testing for improved performance
- [ ] Custom SSL certificate support
- [ ] Email notifications for results

### Version 2.0 (future)
- [ ] Web interface for configuration
- [ ] SIEM solution integration
- [ ] REST API for automation

## 📞 Support

For help or to report issues:
- 📧 Contact the author: Hubert Cornet
- 🐛 Open an issue on the project repository
- 📚 Consult the technical documentation

## 📄 License

This project is under MIT license. See the `LICENSE` file for more details.

---

**⭐ If this script was useful to you, feel free to give it a star!**

---

*Last updated: September 3, 2025*