Skip to content

Commit 2f06527

Browse files
vishnurajkvvishnurajkv
committed
Initial commit of SecNode API framework
0 parents  commit 2f06527

11 files changed

Lines changed: 1021 additions & 0 deletions

‎.github/workflows/secnode-pentest.yml‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
name: secnode-api-pentest
2+
3+
on:
4+
pull_request:
5+
6+
jobs:
7+
security-scan:
8+
runs-on: ubuntu-latest
9+
steps:
10+
- uses: actions/checkout@v4
11+
12+
- name: Set up Python
13+
uses: actions/setup-python@v5
14+
with:
15+
python-version: '3.10'
16+
17+
- name: Install SecNode
18+
run: pip install -r requirements.txt
19+
20+
- name: Run SecNode Scan
21+
env:
22+
SECNODE_LLM: ${{ secrets.SECNODE_LLM }}
23+
OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
24+
run: python3 secnodeapi.py --target https://staging-api.example.com/swagger.json

‎.gitignore‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# Environments
2+
venv/
3+
env/
4+
.venv/
5+
.env
6+
7+
# Application results
8+
results/
9+
10+
# Python Cache
11+
__pycache__/
12+
*.pyc
13+
*.pyo
14+
*.pyd
15+
16+
# macOS
17+
.DS_Store
18+
19+
# IDEs
20+
.idea/
21+
.vscode/

‎CONTRIBUTING.md‎

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
# Contributing to SecNode API
2+
3+
Thank you for your interest in contributing to SecNode API! This guide will help you get started with development and contributions to our autonomous, AI-augmented black-box penetration testing framework.
4+
5+
## 🚀 Development Setup
6+
7+
### Prerequisites
8+
9+
- Python 3.9+
10+
- Git
11+
12+
### Local Development
13+
14+
1. **Clone the repository**
15+
```bash
16+
git clone https://github.com/secnode/secnodeapi.git
17+
cd secnodeapi
18+
```
19+
20+
2. **Set up a virtual environment**
21+
```bash
22+
python3 -m venv venv
23+
source venv/bin/activate
24+
```
25+
26+
3. **Install dependencies**
27+
```bash
28+
pip install -r requirements.txt
29+
```
30+
31+
4. **Configure your LLM provider**
32+
```bash
33+
export SECNODE_LLM="openai/gpt-4o"
34+
export OPENAI_API_KEY="your-api-key"
35+
```
36+
37+
5. **Run SecNode in development mode**
38+
```bash
39+
python3 secnodeapi.py --target https://api.example.com/swagger.json
40+
```
41+
42+
## 🧠 Enhancing the AI Engine
43+
44+
SecNode relies heavily on its `ai_engine.py` component for cognitive test generation and verification.
45+
46+
### Quick Guide
47+
48+
1. **Understand Pipeline Flow:** Familiarize yourself with how `schema_fetcher`, `ai_engine`, and `test_executor` interact.
49+
2. **Improve System Prompts:** If adding support for new vulnerability classes, update the system prompts inside `generate_test_cases()`.
50+
3. **Refine Heuristics:** If the engine is flagging false positives, refine the Chain-of-Thought heuristics inside `_evaluate_single_result()`.
51+
4. **Submit via PR** with clear descriptions of the accuracy/coverage improvement.
52+
53+
## 🔧 Contributing Code
54+
55+
### Pull Request Process
56+
57+
1. **Create an issue first** - Describe the problem or feature you want to build.
58+
2. **Fork and branch** - Work from the `main` branch.
59+
3. **Make your changes** - Follow existing code style (use `structlog` for logging, fully type-hint signatures).
60+
4. **Write/update tests** - Ensure new parsing or networking logic handles edge cases.
61+
5. **Submit PR** - Link to the original issue and provide context.
62+
63+
### PR Guidelines
64+
65+
- **Clear description** - Explain what changed and why.
66+
- **Small, focused changes** - Do not submit massive rewrites; isolate one feature/fix per PR.
67+
- **Include examples** - Show before/after behavior (e.g., sample proxy output, generated findings).
68+
- **Update documentation** - If adding new CLI features, update `README.md`.
69+
70+
### Code Style
71+
72+
- Follow PEP 8 with a 100-character line limit.
73+
- Use Python type hints (`typing`) for all functions and Pydantic models.
74+
- Write docstrings for all public methods.
75+
- Keep functions tightly focused and under 100 lines.
76+
- No `print()` statements — use `structlog` (`logger.info()`, `logger.error()`).
77+
78+
## 🐛 Reporting Issues
79+
80+
When reporting bugs, please include:
81+
82+
- Python version and OS
83+
- LLM Provider and Model being used
84+
- Target API structure (if possible to share safely)
85+
- Full error traceback
86+
- Steps to reproduce
87+
- Expected vs actual behavior
88+
89+
## 💡 Feature Requests
90+
91+
We heavily welcome new feature ideas! Please:
92+
93+
- Check existing issues first.
94+
- Describe the core use case clearly.
95+
- Explain why it would benefit security engineers or developers.
96+
- Consider the technical implementation approach.
97+
98+
## ✨ Recognition
99+
100+
We value all contributions! Contributors will be:
101+
- Listed in our release notes
102+
- Formally recognized in the repository's contributors list
103+
104+
---
105+
106+
**Questions?** Create a GitHub Discussion or Issue. We're here to help you hack smarter!

‎README.md‎

Lines changed: 156 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,156 @@
1+
<div align="center">
2+
3+
# SecNode API
4+
5+
### Autonomous, AI-augmented black-box API penetration testing framework.
6+
7+
<br/>
8+
9+
<a href="https://github.com/secnode/secnodeapi"><img src="https://img.shields.io/github/stars/secnode/secnodeapi?style=flat-square" alt="GitHub Stars"></a>
10+
<a href="LICENSE"><img src="https://img.shields.io/badge/License-Apache%202.0-3b82f6?style=flat-square" alt="License"></a>
11+
<a href="https://pypi.org/project/secnodeapi/"><img src="https://img.shields.io/pypi/v/secnodeapi?style=flat-square" alt="PyPI Version"></a>
12+
13+
</div>
14+
15+
---
16+
17+
## SecNode Overview
18+
SecNode API is an autonomous AI agentic penetration testing framework in Python. It ingests Swagger/OpenAPI schemas, reasons over the business context with an LLM, generates highly contextual and adversarial test cases, executes them concurrently, and automatically produces audit-grade vulnerability reports.
19+
20+
Built for security engineers and developers who need robust Dynamic Application Security Testing (DAST) without the noise of false positives.
21+
22+
**Key Capabilities:**
23+
24+
- **Zero False Positives Workflow** via strict validation and deterministic re-execution.
25+
- **Deep Business Logic Analysis** tailored to your API's specific domain and trust boundaries.
26+
- **OWASP API Security Top 10 (2023) Coverage**, perfectly mapped to BOLA, BOPLA, BFLA, and more.
27+
- **Asynchronous Execution Engine** pushing high-volume, concurrent attack probes.
28+
- **Provider-Agnostic LLM Integration** powered by LiteLLM (OpenAI, Anthropic, Gemini, local models).
29+
- **Auto-Generated Reporting** producing actionable Markdown and machine-readable JSON outputs.
30+
31+
## Use Cases
32+
- **Application Security Testing** - Detect and validate critical API vulnerabilities automatically in CI/CD.
33+
- **Rapid Penetration Testing** - Execute an entire API pentest in minutes rather than weeks.
34+
- **Bug Bounty Automation** - Automatically discover business logic flows and exploit chains.
35+
- **Continuous Compliance** - Maintain a continuous security posture aligned with OWASP Top 10.
36+
37+
## 🚀 Quick Start
38+
**Prerequisites:**
39+
- Python 3.9+
40+
- An LLM API key (e.g. OpenAI)
41+
42+
### Installation & First Scan
43+
```bash
44+
# Clone the repository
45+
git clone https://github.com/secnode/secnodeapi.git
46+
cd secnodeapi
47+
48+
# Setup virtual environment and dependencies
49+
python3 -m venv venv
50+
source venv/bin/activate
51+
pip install -r requirements.txt
52+
53+
# Configure your AI provider
54+
export SECNODE_LLM="openai/gpt-4o"
55+
export OPENAI_API_KEY="your-api-key"
56+
57+
# Run your first security assessment
58+
python3 secnodeapi.py --target https://api.your-app.com/swagger.yaml
59+
```
60+
61+
> [!NOTE]
62+
> Scan reports and findings are saved to timestamped directories in `results/<target_domain>_<timestamp>/`
63+
64+
---
65+
66+
## ✨ Features
67+
68+
### Agentic Security Testing Engine
69+
SecNode operates via a strict agentic pipeline:
70+
71+
- **Schema Fetcher** - Downloads, parses, and resolves complex OpenAPI definitions.
72+
- **Cognitive AI Engine** - Reads the API structure, deduces trust boundaries, and flags high-risk flows.
73+
- **Exploit Generator** - Specifically generates deep attack vectors like UUID swapping or parameter mass assignment.
74+
- **Parallel Test Executor** - Fires async requests rapidly while respecting internal rate limits.
75+
- **False-Positive Eliminator** - Uses `validate_and_retest` loop with deterministic re-execution and a "Chain-of-Thought" elite app-sec triage prompt.
76+
77+
### Comprehensive Vulnerability Detection
78+
SecNode rigorously hunts for:
79+
80+
- **Access Control** - BOLA (IDOR) and BFLA (Privilege Escalation).
81+
- **Mass Assignment** - BOPLA and sensitive field overriding.
82+
- **Resource Constraints** - Rate Limit bypasses, infinite pagination.
83+
- **Business Logic** - State machine skipping, negative price manipulation, validation bypass.
84+
85+
---
86+
87+
## Usage Examples
88+
89+
### Basic Usage
90+
```bash
91+
# Scan an API using a remote Swagger JSON
92+
python3 secnodeapi.py --target http://vulnapi.your-app.com/swagger.json
93+
94+
# Scan an API using a local OpenAPI YAML file
95+
python3 secnodeapi.py --target ./docs/openapi.yaml
96+
```
97+
98+
### Advanced Testing Scenarios
99+
```bash
100+
# Authenticated Testing (using inline Bearer token)
101+
python3 secnodeapi.py --target https://api.your-app.com/docs \
102+
--auth-header "Authorization: Bearer my-jwt-token"
103+
104+
# Authenticated Testing (using a JSON auth file)
105+
python3 secnodeapi.py --target https://api.your-app.com/docs \
106+
--auth-file ./config/auth.json
107+
108+
# Proxy Traffic (e.g. send traffic through Burp Suite/ZAP for manual review)
109+
python3 secnodeapi.py --target https://api.your-app.com/docs \
110+
--proxy http://127.0.0.1:8080
111+
112+
# Control Concurrency (Scale execution speed)
113+
python3 secnodeapi.py --target https://api.your-app.com/docs \
114+
--concurrency 10
115+
```
116+
117+
### CI/CD (GitHub Actions)
118+
SecNode API can be easily integrated into your DevSecOps pipeline to scan staging APIs before deployment.
119+
120+
```yaml
121+
name: secnode-api-pentest
122+
123+
on:
124+
pull_request:
125+
126+
jobs:
127+
security-scan:
128+
runs-on: ubuntu-latest
129+
steps:
130+
- uses: actions/checkout@v3
131+
132+
- name: Set up Python
133+
uses: actions/setup-python@v4
134+
with:
135+
python-version: '3.10'
136+
137+
- name: Install SecNode
138+
run: pip install -r requirements.txt
139+
140+
- name: Run SecNode Scan
141+
env:
142+
SECNODE_LLM: ${{ secrets.SECNODE_LLM }}
143+
OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
144+
run: python3 secnodeapi.py --target https://staging-api.example.com/swagger.json
145+
```
146+
147+
### Configuration
148+
```bash
149+
# Default behavior uses GPT-4o
150+
export SECNODE_LLM="openai/gpt-4o"
151+
export OPENAI_API_KEY="sk-..."
152+
153+
# Or use Anthropic
154+
export SECNODE_LLM="anthropic/claude-3-5-sonnet-20241022"
155+
export ANTHROPIC_API_KEY="sk-ant-..."
156+
```

0 commit comments

Comments
 (0)