You are working on NocturneRecon, a state-of-the-art OSINT and passive reconnaissance framework designed for cybersecurity professionals. The framework focuses on API-free reconnaissance techniques to maintain operational security (OPSEC) and work in air-gapped environments.
nocturnerecon/
āāā main.py # CLI entry point
āāā core/ # Core framework
ā āāā cli.py # Argument parsing
ā āāā utils.py # Utilities and color printing
ā āāā config.py # Configuration management
āāā modules/ # Reconnaissance modules
ā āāā subdomain_enum.py # Subdomain enumeration
ā āāā email_enum.py # Email harvesting
ā āāā cert_parser.py # Certificate transparency
ā āāā github_enum.py # GitHub intelligence
ā āāā breach_parser.py # Breach data analysis
āāā scrapers/ # Web scraping utilities
āāā output/ # Output directories
āāā scripts/ # Installation and utility scripts
- Python 3.8+: Core language
- requests: HTTP client
- beautifulsoup4: HTML parsing
- dnspython: DNS operations
- colorama: Terminal colors
- pyyaml: Configuration files
- Follow Project Patterns: Use existing utility functions from
core/utils.py
- Error Handling: Always include proper try-catch blocks
- OPSEC Awareness: Include rate limiting and user agent rotation
- Logging: Use the color-coded print functions (
print_info
, print_success
, etc.)
- Configuration: Read settings from the config system
- Output: Support all three output formats (JSON, CSV, TXT)
from core.utils import print_info, print_success, print_error
from core.config import get_user_agent
class NewModule:
def __init__(self, args, config):
self.args = args
self.config = config
self.target = clean_domain(args.target)
def run(self):
print_info(f"Starting {self.__class__.__name__} for: {self.target}")
# Implementation here
return results
headers = {'User-Agent': get_user_agent(self.config)}
response = requests.get(url, headers=headers, timeout=self.timeout)
time.sleep(self.args.delay) # Rate limiting
try:
result = risky_operation()
print_success(f"Operation completed: {result}")
except requests.RequestException as e:
print_error(f"Network error: {e}")
except Exception as e:
print_error(f"Unexpected error: {e}")
if self.verbose:
import traceback
traceback.print_exc()
- Create Module File: Add to
modules/
directory
- Implement Required Methods:
__init__
, run
, save_results
- Update CLI: Add new module option to
core/cli.py
- Add Configuration: Update default config in
core/config.py
- Test Thoroughly: Verify with known targets
- Check Current Implementation: Understand existing patterns
- Maintain Compatibility: Don't break existing functionality
- Add Configuration Options: Make features configurable
- Update Documentation: Modify relevant docstrings
- Test Edge Cases: Verify error handling
data = {
'target': self.target,
'timestamp': time.strftime('%Y-%m-%d %H:%M:%S'),
'total_found': len(results),
'results': results
}
save_to_json(data, filepath)
csv_data = [{'field': item.field} for item in results]
save_to_csv(csv_data, filepath, ['field'])
- Use
--verbose
flag for detailed output
- Check network connectivity with simple requests first
- Validate target domain format
- Test with known working targets
- Rate Limiting: Don't hammer services
- User Agent Rotation: Randomize request headers
- Proxy Support: Design with proxy chains in mind
- Data Sanitization: Clean output data
- Error Disclosure: Don't leak internal details
- Store sensitive data in logs
- Use hardcoded credentials
- Ignore rate limiting
- Skip input validation
- Expose debug information to users
- Focus on passive techniques first
- Validate all discovered subdomains
- Filter results to target domain only
- Support multiple wordlists
- Use search engine dorking
- Validate email format
- Filter to target domain only
- Implement permutation patterns
- Parse certificate transparency logs
- Extract SANs and CNs
- Handle expired certificates appropriately
- Deduplicate results
- Search across different GitHub content types
- Detect potential secrets in code
- Extract emails from commits
- Respect GitHub's rate limits
- Handle large files efficiently
- Support multiple file formats
- Never store plaintext passwords
- Provide metadata only
# In core/config.py DEFAULT_CONFIG
'new_module': {
'option1': 'default_value',
'option2': True,
'option_list': ['item1', 'item2']
}
# In module code
config = self.config.get('new_module', {})
option1 = config.get('option1', 'fallback')
# Get user agent
user_agent = get_user_agent(self.config)
# Get DNS servers
dns_servers = get_dns_servers(self.config)
# Check if feature is enabled
if is_feature_enabled(self.config, 'module_name', 'feature_name'):
# Feature implementation
import threading
def worker(item):
# Process item
with self.lock:
self.results.add(processed_item)
threads = []
for item in items:
thread = threading.Thread(target=worker, args=(item,))
thread.daemon = True
thread.start()
threads.append(thread)
for thread in threads:
thread.join()
def process_file(filepath):
try:
with open(filepath, 'r', encoding='utf-8') as f:
for line_num, line in enumerate(f):
line = line.strip()
if line:
yield line
except Exception as e:
print_error(f"Error reading {filepath}: {e}")
- Does this follow the project's error handling patterns?
- Is rate limiting implemented appropriately?
- Are configuration options being used correctly?
- Will this work with all supported output formats?
- Is the code OPSEC-aware?
- Are there any hardcoded values that should be configurable?
- Is input validation sufficient?
- Are results being filtered and deduplicated properly?
- Check existing modules for patterns
- Review
core/utils.py
for available utilities
- Look at
core/config.py
for configuration options
- Test with verbose mode for debugging
- Import Errors: Check module paths and dependencies
- Network Issues: Verify connectivity and DNS resolution
- Config Issues: Validate YAML syntax and option names
- Output Issues: Check file permissions and directory existence
Remember: NocturneRecon prioritizes stealth and OPSEC. Always consider the operational impact of code changes.