PROJECT OVERVIEW:
This project aims to build a Single Page Application (SPA) called 'KodGüven' (CodeSecure in English) that leverages AI to automatically scan code repositories for security vulnerabilities. The core problem it addresses is the difficulty and time-consuming nature of manual code security audits, especially for large or complex codebases like the Linux kernel. Inspired by the discovery of a 23-year-old Linux kernel vulnerability using AI (Claude Code), KodGüven provides developers with an efficient, proactive way to identify and fix security flaws early in the development lifecycle. The value proposition is enhanced software security, reduced development risk, and faster time-to-market by automating a critical but often resource-intensive process.
TECH STACK:
- Frontend Framework: React.js (using Vite for fast development setup).
- Styling: Tailwind CSS for rapid UI development and consistent styling.
- State Management: Zustand for efficient and simple global state management.
- Routing: React Router DOM for client-side routing within the SPA.
- API Interaction: Axios for making HTTP requests to a hypothetical backend API.
- UI Components: Headless UI for accessible and customizable component primitives (like modals, dropdowns).
- Icons: Heroicons for a clean and consistent icon set.
- Date Formatting: date-fns for utility in displaying timestamps.
CORE FEATURES:
1. **Repository Integration & Scanning:**
* **User Flow:** User navigates to the 'Integrations' page, clicks 'Connect Repository', selects a provider (GitHub, GitLab, Bitbucket), authenticates via OAuth, and grants necessary permissions. User then selects a specific repository to scan and clicks 'Start Scan'. The system initiates an AI-powered analysis. A loading indicator is displayed. Upon completion, the user is redirected to the 'Dashboard' or a dedicated 'Scan Results' page.
* **Details:** The frontend will manage the OAuth flow, display connected repositories, and allow selection. A button will trigger a POST request to the backend API with the repository URL and branch. The backend will handle cloning the repo and initiating the AI analysis.
2. **AI-Powered Vulnerability Analysis:**
* **User Flow:** This is the core backend process, triggered after repository selection. The AI model (simulated or actual) receives the codebase, identifies potential vulnerabilities (e.g., buffer overflows, SQL injection, XSS, legacy code patterns), and categorizes them by severity and type.
* **Details:** The SPA will display a real-time progress indicator (e.g., 'Analyzing file X of Y', 'Scanning for buffer overflows...'). This involves polling the backend for status updates or using WebSockets.
3. **Detailed Vulnerability Reporting:**
* **User Flow:** After a scan completes, the user views a dashboard listing all detected vulnerabilities. Clicking on a specific vulnerability reveals a detailed view: description of the flaw, affected file(s) and line number(s), severity level (e.g., Critical, High, Medium, Low), potential impact, and CVE information if applicable.
* **Details:** The results page will present data clearly. A table or list view for overview, and a modal or separate page for detailed breakdown. Each vulnerability should have a unique ID.
4. **Automated Remediation Suggestions:**
* **User Flow:** Within the detailed vulnerability report, the AI provides suggested code snippets or explanations on how to fix the identified issue. For example, for an SQL injection, it might suggest using parameterized queries and provide a corrected code example.
* **Details:** This section displays plain text explanations and code blocks. The AI's output needs to be parsed and presented cleanly. Suggestions should be actionable and context-aware.
5. **User Dashboard & History:**
* **User Flow:** A central dashboard displays a summary of recent scans, overall project security score, and a history of past scans with their respective results.
* **Details:** Provides an overview and quick access to previous scan results, allowing users to track improvements over time.
UI/UX DESIGN:
- **Layout:** A clean, modern, single-page application layout. A persistent sidebar navigation (collapsible on smaller screens) for 'Dashboard', 'Integrations', 'Scan History', 'Settings'. The main content area displays the active section.
- **Color Palette:** Primary: Dark blue (#1A202C - dark background). Secondary: A vibrant accent color like teal or green (#4FD1C5 or #68D391) for buttons, active states, and highlights. Neutrals: Grays for text and borders (#A0AEC0, #CBD5E0). Warning/Error colors: Red/Orange (#F56565, #ED8936).
- **Typography:** A sans-serif font family like Inter or Poppins for readability. Clear hierarchy using font weights and sizes (e.g., H1 for page titles, H2 for section titles, body text, captions).
- **Responsive Design:** Mobile-first approach. Sidebar collapses into a hamburger menu on small screens. Content reflows and scales appropriately. Ensure usability across devices from mobile phones to large desktop monitors.
- **Interactivity:** Subtle hover effects on buttons and links. Smooth transitions for page loads and modal appearances. Clear loading states (spinners, skeleton screens).
COMPONENT BREAKDOWN:
- **`App.jsx`:** Main application component, sets up routing and global layout.
- **`Layout.jsx`:** Contains the main structure, including the sidebar and main content area.
- **`Sidebar.jsx`:** Navigation menu component. Props: `routes` (array of navigation items).
- **`Header.jsx`:** Top bar, potentially showing user info or global actions.
- **`DashboardPage.jsx`:** Displays overview, recent scans, security score.
- `SecurityScoreChart.jsx`: Visual representation of security score.
- `RecentScansList.jsx`: List of the latest scan results.
- **`IntegrationsPage.jsx`:** Manages repository connections.
- `RepoList.jsx`: Displays connected and available repositories.
- `ConnectButton.jsx`: Handles OAuth connection flow.
- `ScanTriggerButton.jsx`: Initiates a new scan for a selected repo.
- **`ScanHistoryPage.jsx`:** Lists all past scans.
- `ScanRow.jsx`: Represents a single scan in the history list. Props: `scan` (object with scan details).
- **`VulnerabilityDetailsPage.jsx`:** Shows detailed information for a selected vulnerability.
- `VulnerabilityHeader.jsx`: Displays title, severity, file location.
- `VulnerabilityDescription.jsx`: Detailed explanation of the vulnerability.
- `RemediationSuggesstions.jsx`: Displays AI-generated fix suggestions.
- `CodeSnippet.jsx`: Renders code blocks for suggestions.
- **`LoadingSpinner.jsx`:** Reusable spinner component.
- **`Modal.jsx`:** Generic modal component. Props: `isOpen`, `onClose`, `children`.
- **`Alert.jsx`:** For displaying informational messages or errors.
DATA MODEL:
- **`scanResults` State:** An object or array storing scan data. Example structure:
```json
{
"scanId": "uuid-1234",
"repository": "github.com/user/repo",
"branch": "main",
"status": "completed", // 'pending', 'running', 'completed', 'failed'
"scanDate": "2023-10-27T10:00:00Z",
"overallScore": 7.5,
"vulnerabilities": [
{
"vulnId": "CVE-2023-XXXX",
"name": "Heap Buffer Overflow",
"severity": "Critical", // Critical, High, Medium, Low
"file": "/path/to/vulnerable/file.c",
"line": 157,
"description": "A remotely exploitable heap buffer overflow vulnerability...",
"impact": "Remote code execution.",
"suggestions": [
{
"type": "code_change",
"code": "// Fix: Use safer function like strncpy or allocate dynamically.\nstrncpy(buffer, src, sizeof(buffer) - 1);\nbuffer[sizeof(buffer) - 1] = '\0';",
"explanation": "Ensure that the destination buffer is never overflowed by limiting the copy operation to the buffer size."
}
]
}
// ... more vulnerabilities
]
}
```
- **`connectedRepos` State:** An array of connected repository objects.
- **`auth` State:** User authentication token and status.
- **Local Storage:** Used for persisting authentication tokens and user preferences.
ANIMATIONS & INTERACTIONS:
- **Page Transitions:** Subtle fade-in/fade-out transitions between pages using libraries like Framer Motion or CSS transitions.
- **Button Hovers:** Slight scale-up or background color change on button hover states.
- **Loading States:** Use `react-loader-spinner` or similar for scan progress. Display skeleton loaders for lists and tables while data is being fetched.
- **Sidebar Collapse:** Smooth slide animation when the sidebar is collapsed or expanded.
- **Alerts/Modals:** Fade-in and slide-up animations for modals and alert notifications.
- **Micro-interactions:** Subtle animations on status indicators (e.g., a pulsating dot for 'running' scans).
EDGE CASES:
- **No Repositories Connected:** Display a clear message and a prominent button to connect a repository on the Integrations page.
- **Scan Failure:** Clearly indicate scan failures in the history and dashboard, providing a reason if available from the backend.
- **No Vulnerabilities Found:** Display a success message (e.g., "No critical vulnerabilities found in this scan.") with a positive security score.
- **API Errors:** Gracefully handle network errors or API-down situations, showing user-friendly messages.
- **Empty State for Lists:** Display messages like "No scan history found." or "No vulnerabilities detected." when relevant lists are empty.
- **Accessibility (a11y):** Ensure all interactive elements have proper ARIA attributes, focus management is handled correctly, and color contrast meets WCAG standards. Use semantic HTML.
- **Input Validation:** Validate repository URLs and other user inputs before submission.
SAMPLE DATA (Mock Data Format):
```javascript
// Example for Scan History Page
const mockScanHistory = [
{
scanId: "scan-abc",
repository: "github.com/example/webapp",
branch: "develop",
scanDate: "2024-03-15T08:30:00Z",
status: "completed",
overallScore: 8.2,
vulnerabilityCount: 3
},
{
scanId: "scan-def",
repository: "github.com/example/api",
branch: "main",
scanDate: "2024-03-10T14:00:00Z",
status: "completed",
overallScore: 6.5,
vulnerabilityCount: 7
},
{
scanId: "scan-ghi",
repository: "github.com/example/webapp",
branch: "develop",
scanDate: "2024-03-14T08:30:00Z",
status: "failed",
overallScore: null,
vulnerabilityCount: 0
}
];
// Example for Vulnerability Details Page (within a completed scan)
const mockVulnerabilityDetails = {
scanId: "scan-abc",
repository: "github.com/example/webapp",
vulnerabilities: [
{
vulnId: "LLVM-MISC-1",
name: "Potential Buffer Overflow",
severity: "High",
file: "src/utils/string_ops.c",
line: 42,
description: "The function `process_string` does not check the size of the input string before copying it into a fixed-size buffer, potentially leading to a buffer overflow.",
impact: "Could lead to application crash or potential code execution if exploited.",
suggestions: [
{
type: "code_change",
code: "#include <string.h>\n\nvoid process_string(const char* input) {\n char buffer[128];\n // Use strncpy with size limit to prevent overflow\n strncpy(buffer, input, sizeof(buffer) - 1);\n buffer[sizeof(buffer) - 1] = '\0'; // Ensure null termination\n // ... process buffer ...\n}",
explanation: "Replace `strcpy` with `strncpy` and explicitly handle null termination to prevent overflows. Alternatively, use bounds-checked functions if available."
},
{
type: "best_practice",
explanation: "Always validate input sizes against buffer capacities before performing copy operations."
}
]
},
{
vulnId: "SEC-XSS-2",
name: "Reflected Cross-Site Scripting (XSS)",
severity: "Medium",
file: "routes/handlers.js",
line: 115,
description: "User input from the 'query' parameter is directly rendered in the HTML response without proper sanitization.",
impact: "Allows attackers to inject malicious scripts into users' browsers.",
suggestions: [
{
type: "code_change",
code: "// Sanitize user input before rendering\nconst sanitizedQuery = DOMPurify.sanitize(req.query.query);\nres.send(`<h1>Search results for: ${sanitizedQuery}</h1>`);",
explanation: "Use a reliable sanitization library like DOMPurify to escape or remove malicious HTML/JavaScript code from user inputs before rendering them in the HTML response."
}
]
}
// ... more mock vulnerabilities
]
};
// Example for Repository List (Integrations Page)
const mockConnectedRepositories = [
{ id: 'repo-1', name: 'github.com/user/project-alpha', provider: 'GitHub', lastScan: '2024-03-14T09:00:00Z' },
{ id: 'repo-2', name: 'gitlab.com/user/internal-tool', provider: 'GitLab', lastScan: null } // No scan yet
];
// Example for Dashboard Overview
const mockDashboardSummary = {
totalProjects: 5,
averageScore: 7.8,
criticalVulnerabilities: 2,
highVulnerabilities: 5,
recentActivity: "Scan completed for github.com/user/project-alpha (2024-03-15)"
};
DEPLOYMENT NOTES:
- **Build:** Configure Vite for production builds (`vite build`). Ensure environment variables are handled correctly (e.g., using `.env` files).
- **Environment Variables:** Use `VITE_` prefix for frontend environment variables (e.g., `VITE_API_URL`). Backend API URL, authentication keys, and any external service keys should be managed as environment variables on the server/deployment platform.
- **Performance:** Code-split routes and components using `React.lazy` and `Suspense`. Optimize images and other assets. Implement efficient state management to avoid unnecessary re-renders. Utilize Tailwind CSS's JIT mode for optimal build sizes.
- **API Gateway:** Consider using an API Gateway for managing backend services, rate limiting, and authentication if the backend scales.
- **CI/CD:** Set up a CI/CD pipeline (e.g., using GitHub Actions) to automate testing, building, and deployment.
- **Error Monitoring:** Integrate an error tracking service like Sentry or LogRocket for real-time error monitoring and debugging.
- **Security:** Ensure secure handling of API keys and authentication tokens. Implement HTTPS. Regularly update dependencies to patch security vulnerabilities in the stack itself.