├── README.md ├── api_fuzzer.py └── requirements.txt /README.md: -------------------------------------------------------------------------------- 1 | # API Fuzzer 2 | 3 | API Fuzzer is a Python tool designed for security testing and discovering valid endpoints in web applications by fuzzing API endpoints using a wordlist. It is built to efficiently handle and retry failed requests, log unusual response statuses, and save the discovered endpoints for further examination. 4 | 5 | It was created to demonstrate a simple codebase to automate the fuzzing process for a the "Web Fuzzing" HTB Module. 6 | 7 | ## Installation 8 | 9 | This project requires Python 3.6+ with the `requests` and `colorama` libraries. Install the required libraries using pip: 10 | 11 | ```bash 12 | pip install requests colorama 13 | ``` 14 | 15 | or 16 | 17 | ```bash 18 | pip install -r requirements.txt 19 | ``` 20 | 21 | ## Usage 22 | 23 | To use API Fuzzer, you need to specify the base URL of the API you want to test. Optionally, you can customize several parameters like wordlist path, rate limit, headers, and request timeout. 24 | 25 | ```bash 26 | python api_fuzzer.py http://example.com/api 27 | ``` 28 | 29 | ### Options 30 | 31 | - `--wordlist`: Path to the wordlist for fuzzing endpoints. If omitted, a default wordlist will be loaded. 32 | - `--rate-limit`: Limits the rate of requests per second. Default is no limit. 33 | - `--headers`: Custom headers to use in requests, in JSON format. 34 | - `--timeout`: Timeout for each request in seconds. Default is 10 seconds. 35 | - `--output`: File path to save discovered valid endpoints. 36 | - `-o`: Quick save to `discovered_endpoints.txt`. 37 | 38 | ```bash 39 | python api_fuzzer.py http://example.com/api --wordlist ./path/to/wordlist.txt --rate-limit 10 --headers '{"Content-Type": "application/json"}' --timeout 5 --output results.txt 40 | ``` 41 | -------------------------------------------------------------------------------- /api_fuzzer.py: -------------------------------------------------------------------------------- 1 | import requests 2 | import argparse 3 | import urllib.parse 4 | import time 5 | import json 6 | from colorama import Fore, Style, init 7 | from typing import Dict 8 | from requests.adapters import HTTPAdapter 9 | from requests.packages.urllib3.util.retry import Retry 10 | 11 | 12 | class EndpointFuzzer: 13 | """ 14 | A class representing an endpoint fuzzer. 15 | 16 | Attributes: 17 | base_url (str): The base URL of the API. 18 | wordlist_path (str): The path to the wordlist file. 19 | rate_limit (float): The rate limit for sending requests. 20 | headers (Dict[str, str]): The headers to be included in the requests. 21 | timeout (int): The timeout for each request. 22 | discovered_endpoints (List[str]): A list of discovered valid endpoints. 23 | unusual_endpoints (List[Tuple[str, int]]): A list of endpoints with unusual status codes. 24 | total_requests (int): The total number of requests sent. 25 | failed_requests (int): The number of failed requests. 26 | retries (int): The number of retries for failed requests. 27 | status_code_counts (Dict[int, int]): A dictionary mapping status codes to their counts. 28 | session (requests.Session): The session object for making HTTP requests. 29 | 30 | Methods: 31 | create_session(): Creates and configures a session object for making HTTP requests. 32 | increment_retries(): Increments the number of retries for failed requests. 33 | load_wordlist(): Loads the wordlist from a file or fetches it remotely. 34 | load_remote_wordlist(): Fetches the wordlist from a remote URL. 35 | fuzz_endpoints(): Starts the fuzzing process by iterating over the wordlist and testing each endpoint. 36 | test_endpoint(endpoint: str): Tests a single endpoint by sending a GET request and analyzing the response. 37 | print_summary(): Prints a summary of the fuzzing results. 38 | save_results(output_file: str): Saves the discovered valid endpoints to a file. 39 | 40 | """ 41 | 42 | def __init__( 43 | self, 44 | base_url: str, 45 | wordlist_path: str = None, 46 | rate_limit: float = None, 47 | headers: Dict[str, str] = None, 48 | timeout: int = 10, 49 | ): 50 | self.base_url = base_url 51 | self.wordlist_path = wordlist_path 52 | self.rate_limit = rate_limit 53 | self.headers = headers if headers else {} 54 | self.timeout = timeout 55 | self.discovered_endpoints = [] 56 | self.unusual_endpoints = [] 57 | self.total_requests = 0 58 | self.failed_requests = 0 59 | self.retries = 0 60 | self.status_code_counts = {} 61 | init(autoreset=True) 62 | self.session = self.create_session() 63 | 64 | def create_session(self): 65 | """ 66 | Creates and configures a session object for making HTTP requests. 67 | 68 | Returns: 69 | requests.Session: The configured session object. 70 | """ 71 | session = requests.Session() 72 | retry_strategy = Retry( 73 | total=5, 74 | backoff_factor=0.1, 75 | status_forcelist=[500, 502, 503, 504], 76 | allowed_methods=["HEAD", "GET", "OPTIONS"], 77 | ) 78 | adapter = HTTPAdapter(max_retries=retry_strategy) 79 | session.mount("http://", adapter) 80 | session.mount("https://", adapter) 81 | return session 82 | 83 | def increment_retries(self): 84 | """ 85 | Increments the number of retries for failed requests. 86 | """ 87 | self.retries += 1 88 | 89 | def load_wordlist(self): 90 | """ 91 | Loads the wordlist from a file or fetches it remotely. 92 | 93 | Returns: 94 | List[str]: The list of words from the wordlist. 95 | """ 96 | if self.wordlist_path: 97 | with open(self.wordlist_path, "r") as f: 98 | words = f.read().splitlines() 99 | print(f"{Fore.CYAN}Loaded wordlist from {self.wordlist_path}.") 100 | else: 101 | words = self.load_remote_wordlist() 102 | return words 103 | 104 | def load_remote_wordlist(self): 105 | """ 106 | Fetches the wordlist from a remote URL. 107 | 108 | Returns: 109 | List[str]: The list of words from the remote wordlist. 110 | """ 111 | seclists_url = "https://raw.githubusercontent.com/danielmiessler/SecLists/master/Discovery/Web-Content/common.txt" 112 | print(f"{Fore.CYAN}Fetching remote wordlist from {seclists_url}...") 113 | try: 114 | response = self.session.get(seclists_url) 115 | response.raise_for_status() 116 | words = response.text.splitlines() 117 | print(f"{Fore.GREEN}Successfully fetched remote wordlist.") 118 | except requests.RequestException as e: 119 | print(f"{Fore.RED}Failed to fetch remote wordlist: {e}") 120 | words = [] 121 | return words 122 | 123 | def fuzz_endpoints(self): 124 | """ 125 | Starts the fuzzing process by iterating over the wordlist and testing each endpoint. 126 | """ 127 | wordlist = self.load_wordlist() 128 | print(f"{Fore.CYAN}Starting fuzzing with {len(wordlist)} words.") 129 | delay = 1 / self.rate_limit if self.rate_limit else 0 130 | for word in wordlist: 131 | self.test_endpoint(word) 132 | if delay: 133 | time.sleep(delay) 134 | self.print_summary() 135 | 136 | def test_endpoint(self, endpoint: str): 137 | """ 138 | Tests a single endpoint by sending a GET request and analyzing the response. 139 | 140 | Args: 141 | endpoint (str): The endpoint to test. 142 | """ 143 | full_url = urllib.parse.urljoin(self.base_url, endpoint) 144 | try: 145 | response = self.session.get( 146 | full_url, headers=self.headers, timeout=self.timeout 147 | ) 148 | self.total_requests += 1 149 | if response.status_code in [500, 502, 503, 504]: 150 | self.increment_retries() 151 | status_code = response.status_code 152 | self.status_code_counts[status_code] = ( 153 | self.status_code_counts.get(status_code, 0) + 1 154 | ) 155 | if status_code == 200: 156 | print( 157 | f"{Fore.GREEN}[+] Valid endpoint found: {full_url} (Status code: {status_code})" 158 | ) 159 | self.discovered_endpoints.append(full_url) 160 | elif status_code != 404: 161 | print( 162 | f"{Fore.MAGENTA}[!] Unusual status code for {full_url} (Status code: {status_code})" 163 | ) 164 | self.unusual_endpoints.append((full_url, status_code)) 165 | else: 166 | print( 167 | f"{Fore.YELLOW}[-] Invalid endpoint: {full_url} (Status code: {status_code})" 168 | ) 169 | except requests.RequestException as e: 170 | self.total_requests += 1 171 | self.failed_requests += 1 172 | print(f"{Fore.RED}[!] Request failed for {full_url}: {e}") 173 | 174 | def print_summary(self): 175 | """ 176 | Prints a summary of the fuzzing results. 177 | """ 178 | print(f"\n{Fore.CYAN}Fuzzing completed.") 179 | print(f"{Fore.CYAN}Total requests: {self.total_requests}") 180 | print(f"{Fore.RED}Failed requests: {self.failed_requests}") 181 | print(f"{Fore.YELLOW}Retries: {self.retries}") 182 | print(f"{Fore.CYAN}Status code counts:") 183 | for status_code, count in self.status_code_counts.items(): 184 | print(f"{Fore.CYAN}{status_code}: {count}") 185 | 186 | if self.discovered_endpoints: 187 | print(f"{Fore.GREEN}Found valid endpoints:") 188 | for endpoint in self.discovered_endpoints: 189 | print(f"{Fore.GREEN}- {endpoint}") 190 | else: 191 | print(f"{Fore.RED}No valid endpoints found.") 192 | 193 | if self.unusual_endpoints: 194 | print(f"{Fore.MAGENTA}Unusual status codes:") 195 | for endpoint, status_code in self.unusual_endpoints: 196 | print(f"{Fore.MAGENTA}{status_code}: {endpoint}") 197 | 198 | def save_results(self, output_file: str): 199 | """ 200 | Saves the discovered valid endpoints to a file. 201 | 202 | Args: 203 | output_file (str): The path to the output file. 204 | """ 205 | if output_file: 206 | with open(output_file, "w") as f: 207 | for endpoint in self.discovered_endpoints: 208 | f.write(f"{endpoint}\n") 209 | print(f"{Fore.CYAN}Results saved to {output_file}") 210 | 211 | 212 | if __name__ == "__main__": 213 | parser = argparse.ArgumentParser( 214 | description="Fuzzer for discovering valid endpoints using a wordlist." 215 | ) 216 | parser.add_argument("base_url", nargs="?", help="Base URL of the API to test.") 217 | parser.add_argument( 218 | "--wordlist", 219 | help="Path to the wordlist for fuzzing endpoints. If no wordlist is provided, it will load SecList's common.txt wordlist automatically.", 220 | default=None, 221 | ) 222 | parser.add_argument( 223 | "--rate-limit", 224 | type=float, 225 | help="Rate limit for requests (requests per second).", 226 | default=None, 227 | ) 228 | parser.add_argument( 229 | "--headers", 230 | type=str, 231 | help="Custom headers for requests (JSON format).", 232 | default=None, 233 | ) 234 | parser.add_argument( 235 | "--timeout", type=int, help="Timeout for requests (seconds).", default=10 236 | ) 237 | group = parser.add_mutually_exclusive_group() 238 | group.add_argument("--output", help="File to save discovered endpoints.") 239 | group.add_argument( 240 | "-o", action="store_true", help="Quick save to discovered_endpoints.txt" 241 | ) 242 | args = parser.parse_args() 243 | 244 | if not args.base_url: 245 | parser.print_help() 246 | parser.exit() 247 | 248 | headers = json.loads(args.headers) if args.headers else None 249 | 250 | fuzzer = EndpointFuzzer( 251 | base_url=args.base_url, 252 | wordlist_path=args.wordlist, 253 | rate_limit=args.rate_limit, 254 | headers=headers, 255 | timeout=args.timeout, 256 | ) 257 | fuzzer.fuzz_endpoints() 258 | output_file = "discovered_endpoints.txt" if args.o else args.output 259 | fuzzer.save_results(output_file) 260 | -------------------------------------------------------------------------------- /requirements.txt: -------------------------------------------------------------------------------- 1 | requests 2 | colorama --------------------------------------------------------------------------------