PROJECT OVERVIEW:
The application, named 'Kod Güvenliği Gözcüsü' (Code Security Sentinel), aims to address the critical vulnerability exposed by the Claude Code source code leak via a map file in their NPM registry. The core problem is that developers and companies often unknowingly integrate or expose sensitive information within their codebases, especially through third-party libraries or misconfigurations. This tool provides an automated, real-time code scanning and alerting platform for developers and organizations to instantly detect and mitigate security risks, such as exposed credentials and known vulnerabilities, within their source code and dependencies. The value proposition is to offer peace of mind and robust security by proactively identifying and flagging potential code leaks and vulnerabilities before they can be exploited, thereby preventing costly data breaches and reputational damage.
TECH STACK:
- Frontend: React.js (using Vite for fast development)
- Styling: Tailwind CSS for rapid UI development and consistent design.
- State Management: Zustand for efficient and simple global state management.
- Routing: React Router DOM for client-side routing.
- API Interaction: Axios for HTTP requests.
- Utility Libraries: Lodash for utility functions, date-fns for date handling.
- Form Handling: React Hook Form for efficient form management.
- Icons: Heroicons for a clean icon set.
- Deployment: Vercel or Netlify for seamless deployment.
CORE FEATURES:
1. **URL-Based Code Scanning:**
* User Flow: The user navigates to the main scanning interface. They are presented with a prominent input field labeled 'Enter Code Repository URL or Package Name'. Upon entering a valid URL (e.g., GitHub repo, NPM package link) and clicking 'Scan', a loading indicator appears. The system fetches the relevant code (e.g., by cloning a repo, downloading an npm package). The scanning process begins.
* Details: This feature allows users to input a direct link to a code repository or a package. The backend will handle fetching the necessary files (e.g., cloning the repo, downloading the package). For NPM, it might fetch the tarball. For Git repos, it might clone a specific branch or tag. The fetched code is then passed to the scanning engine.
2. **Sensitive Data Detection:**
* User Flow: During the scanning process initiated by URL input, this feature runs automatically. Detected sensitive data types (API keys, passwords, private keys, tokens) are highlighted in the results report with severity levels.
* Details: Utilizes a combination of regex patterns and potentially some lightweight heuristics to identify common patterns of sensitive information. Examples include keys like `AKIA...`, password formats, JWT tokens, private SSH/PGP keys. Findings are categorized by type and location within the codebase.
3. **Vulnerability Alerting (Dependency Scanning):**
* User Flow: If the scanned URL points to a project with a dependency manifest (e.g., `package.json`, `requirements.txt`), this feature is triggered. The system analyzes the listed dependencies against a known vulnerability database. Alerts are generated for vulnerable packages.
* Details: Integrates with vulnerability databases (like CVE lists, GitHub Security Advisories) to check the versions of listed dependencies. Reports vulnerable packages, their CVE IDs, severity, and potentially suggested version upgrades.
4. **Reporting and Summary:**
* User Flow: After the scan completes, a comprehensive yet easy-to-understand report is displayed. This includes a summary dashboard, detailed findings (sensitive data, vulnerabilities), and actionable recommendations.
* Details: The report page will feature a clear overview: number of sensitive data findings, number of vulnerable dependencies, overall security score. Each finding will be clickable, leading to a detailed view showing the file path, line number, type of finding, and potentially a snippet of the code. Recommendations for remediation will be provided.
5. **Real-time Monitoring (Premium Feature):**
* User Flow: Users can connect their Git repositories (e.g., GitHub, GitLab). Every new commit or merge request triggers an automatic scan. Results are pushed to the user's dashboard or via integrations (Slack, email).
* Details: This requires robust webhook integration and backend infrastructure to handle continuous scanning. It provides proactive security monitoring for active development workflows.
UI/UX DESIGN:
- **Layout:** Single Page Application (SPA) structure. Main navigation on the left sidebar (Scan, Dashboard, History, Settings). Central content area displays the active feature (scanning form, report, history list). Clean, modern, and intuitive interface.
- **Color Palette:** Primary: Deep blue (`#1A202C` - dark background). Secondary: Vibrant cyan (`#00BCD4` - for buttons, links, highlights). Accent: Warning yellow (`#FFC107` - for potential risks) and danger red (`#F44336` - for critical vulnerabilities). Neutral: Grays for text and borders (`#A0AEC0`, `#E2E8F0`).
- **Typography:** Sans-serif font family (e.g., Inter, Roboto). Clear hierarchy using font weights and sizes. Headings: Bold, larger sizes. Body text: Regular weight, readable size.
- **Responsive Design:** Mobile-first approach. Sidebar collapses into a hamburger menu on smaller screens. Content area adapts fluidly. All elements should be usable and legible on devices ranging from mobile phones to large desktops.
- **Component Hierarchy:** `App` -> `Layout` -> (`Sidebar`, `ContentArea`) -> `ScanForm`, `ReportView`, `HistoryList`, `FindingDetail`, etc.
COMPONENT BREAKDOWN:
- `App.jsx`: Root component, sets up routing and global layout.
- `Layout.jsx`: Contains the main structure (Sidebar, ContentArea).
- `Sidebar.jsx`: Navigation links (Scan, Dashboard, History, Settings). Receives `activeLink` prop.
- `ContentArea.jsx`: Renders the content based on the active navigation link.
- `ScanForm.jsx`: Input field for URL, 'Scan' button. Manages form state and submission. Props: `onScanSubmit` (function).
- `LoadingSpinner.jsx`: Displays a visual loading indicator. Props: `size`, `color`.
- `ReportView.jsx`: Displays the scan results. Receives `reportData` (object).
- `SummaryDashboard.jsx`: Shows overall stats. Props: `summary` (object).
- `FindingsList.jsx`: Lists all detected issues. Receives `findings` (array).
- `FindingItem.jsx`: Renders a single finding (type, location, severity). Receives `finding` (object), `onClick` (function).
- `FindingDetailModal.jsx`: Modal for detailed view of a finding. Receives `finding`, `isOpen`, `onClose`.
- `HistoryList.jsx`: Displays a list of past scans. Receives `scanHistory` (array).
- `VulnerabilityBadge.jsx`: Visual indicator for vulnerability severity. Props: `severity` (string).
- `ProtectedRoute.jsx`: Wrapper for routes requiring authentication.
DATA MODEL:
- **State Management (Zustand Store):**
```javascript
// store.js
import create from 'zustand';
const useStore = create((set) => ({
currentUser: null, // { id, email, name }
scanHistory: [], // [{ id, url, timestamp, status, findingsCount, vulnerabilitiesCount }]
currentReport: null, // { url, findings: [], summary: {}, vulnerabilities: [] }
isLoading: false,
error: null,
setLoading: (loading) => set({ isLoading: loading }),
setError: (error) => set({ error }),
addScanToHistory: (scanResult) => set((state) => ({
scanHistory: [scanResult, ...state.scanHistory],
})),
setCurrentReport: (report) => set({ currentReport: report }),
setUser: (user) => set({ currentUser: user }),
}));
export default useStore;
```
- **Mock Data Formats:**
* `ScanResultSummary`:
```json
{
"totalFilesScanned": 1500,
"sensitiveDataFound": 5,
"vulnerableDependencies": 3,
"overallScore": 75 // out of 100
}
```
* `Finding`:
```json
{
"id": "finding-123",
"type": "API Key", // e.g., "Password", "Private Key", "Token", "Known Vulnerability"
"filePath": "src/services/api.js",
"lineNumber": 42,
"snippet": "const apiKey = 'AKIAIOSFODNN7EXAMPLE';",
"severity": "High", // e.g., "Low", "Medium", "High", "Critical"
"cveId": "CVE-2023-XXXX" // Only for vulnerabilities
}
```
* `ScanHistoryItem`:
```json
{
"id": "scan-abc",
"url": "https://github.com/example/repo",
"timestamp": "2023-10-27T10:30:00Z",
"status": "Completed", // e.g., "Scanning", "Failed"
"findingsCount": 8,
"vulnerabilitiesCount": 2
}
```
ANIMATIONS & INTERACTIONS:
- **Button Hovers:** Subtle background color change or slight scale-up on hover.
- **Page Transitions:** Fade-in/fade-out transitions between different sections using `Framer Motion` or CSS transitions.
- **Loading States:** `LoadingSpinner` component displayed during API calls or scanning processes. Skeleton loaders for lists and tables before data arrives.
- **Micro-interactions:** Input field focus states, successful scan confirmation message animation, collapsing/expanding sidebar animation.
- **Report Elements:** Animated progress bars for summary scores, subtle highlighting of new findings upon report load.
EDGE CASES:
- **Empty State:** Display helpful messages and illustrations when scan history is empty, or no findings are detected.
- **Error Handling:** Graceful error messages for network issues, invalid URLs, server errors during scanning. Retry options where applicable.
- **Validation:** Input validation for the URL field (e.g., must be a valid HTTP/S URL or package name format). Backend validation for security.
- **Accessibility (a11y):** Semantic HTML, ARIA attributes where necessary, keyboard navigation support, sufficient color contrast, focus indicators.
- **Rate Limiting:** If integrating with external APIs (like GitHub), implement rate limiting awareness and handling.
- **Large Repositories:** Implement mechanisms to handle large codebases, potentially asynchronous scanning or progress indicators.
SAMPLE DATA:
1. **Valid Repo URL:** `https://github.com/some-user/secure-project`
2. **Valid NPM Package:** `react-router-dom@6.1.1`
3. **Invalid URL:** `htp:/invalid-url`
4. **Mock Scan Result (Summary):**
```json
{
"totalFilesScanned": 2150,
"sensitiveDataFound": 2,
"vulnerableDependencies": 1,
"overallScore": 88
}
```
5. **Mock Finding (Sensitive Data):**
```json
{
"id": "finding-sensitive-001",
"type": "API Key",
"filePath": ".env",
"lineNumber": 5,
"snippet": "STRIPE_SECRET_KEY=sk_test_51Jxxxxxxxxxxxxxxxxxxxxxxx",
"severity": "Critical",
"cveId": null
}
```
6. **Mock Finding (Vulnerability):**
```json
{
"id": "finding-vuln-001",
"type": "Known Vulnerability",
"filePath": "package.json",
"lineNumber": 25,
"snippet": "// Dependency: lodash version 4.17.10",
"severity": "High",
"cveId": "CVE-2020-8203"
}
```
7. **Mock Scan History Item (Completed):**
```json
{
"id": "scan-xyz",
"url": "https://github.com/some-user/old-project",
"timestamp": "2023-10-26T15:00:00Z",
"status": "Completed",
"findingsCount": 12,
"vulnerabilitiesCount": 3
}
```
8. **Mock Scan History Item (Scanning):**
```json
{
"id": "scan-def",
"url": "https://gitlab.com/corp/new-feature",
"timestamp": "2023-10-27T11:00:00Z",
"status": "Scanning",
"findingsCount": 0,
"vulnerabilitiesCount": 0
}
```
9. **Mock Finding (Potential Token):**
```json
{
"id": "finding-token-002",
"type": "Token",
"filePath": "src/utils/auth.js",
"lineNumber": 112,
"snippet": "const userToken = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYW1lIjoiSm9lIn0.aBcDeFgHiJkLmNoPqRsTuVwXyZ12345",
"severity": "Medium",
"cveId": null
}
```
10. **Mock Scan Result (No Issues):**
```json
{
"totalFilesScanned": 500,
"sensitiveDataFound": 0,
"vulnerableDependencies": 0,
"overallScore": 98
}
```
DEPLOYMENT NOTES:
- **Environment Variables:** Use `.env` files for API keys, base URLs, and other configurations. Ensure sensitive variables are not committed to the repository. Vercel/Netlify UI for managing environment variables.
- **Build Settings:** Vite's build command (`npm run build`) creates optimized static assets. Configure base path if deploying to a subdirectory.
- **Performance Optimizations:** Code splitting with React.lazy and Suspense. Image optimization. Efficient state management. Memoization of components where necessary. Lazy loading of non-critical components.
- **HTTPS:** Always use HTTPS for deployment and API communication.
- **CORS:** Configure backend CORS policies appropriately if the frontend and backend are hosted on different domains.
- **Database/Storage:** For scan history and user data, consider a scalable solution like PostgreSQL or MongoDB Atlas, or serverless options like Firebase/Supabase depending on scale.
- **Security:** Sanitize all user inputs. Implement authentication and authorization. Protect against common web vulnerabilities (XSS, CSRF).
- **CI/CD:** Set up a CI/CD pipeline (e.g., GitHub Actions, GitLab CI) for automated testing and deployment.