Skip to content

Commit 1db1f67

Browse files
sabrinahaniffsabrinahaniff
committed
add readme
1 parent 96f2b32 commit 1db1f67

1 file changed

Lines changed: 116 additions & 66 deletions

File tree

‎README.md‎

Lines changed: 116 additions & 66 deletions
Original file line numberDiff line numberDiff line change
@@ -1,109 +1,159 @@
1-
# Cyber Risk Platform
1+
# Cyber Risk
22

3-
A full-stack cyber insurance underwriting platform that automates risk assessment for companies. Built with Spring Boot, PostgreSQL, and AI designed for the kind of workflow a cyber insurance underwriter would use daily.
3+
A full-stack web application that automates cyber insurance risk assessment. Companies submit their security profile, receive a scored risk rating from 0–100, and generate a professional AI-written underwriting memo.
44

5-
## What it does
5+
Built this to explore how AI can automate real workflows in the insurance industry. The scoring model is based on common cybersecurity frameworks (firewall presence, encryption, incident response planning, breach history, etc).
66

7-
1. A company submits their security profile via REST API
8-
2. The risk scoring engine evaluates their posture and generates a score from 0–100
9-
3. AI automatically generates a professional underwriting memo with recommendations
7+
---
8+
9+
## Features
10+
11+
- **Risk Scoring Engine**: scores a company's security posture from 0 to 100 using weighted deductions across 6 security factors
12+
- **AI Memo Generation**: uses LLaMA 3.3 70B via Groq to generate a 3-paragraph professional underwriting memo
13+
- **REST API**: full CRUD endpoints built with Spring Boot and Spring Data JPA
14+
- **React Dashboard**: form-based UI with an animated SVG risk gauge and security breakdown
15+
- **Dockerized**: entire app (backend + database) spins up with one `docker-compose up` command
16+
- **CI/CD**: GitHub Actions pipeline builds and tests on every push to main
17+
18+
---
1019

1120
## Tech Stack
1221

13-
- **Backend:** Java 21, Spring Boot 3.5, Spring Data JPA
14-
- **Database:** PostgreSQL
15-
- **AI Integration:** Groq API (LLaMA 3.3 70B)
16-
- **Containerization:** Docker, Docker Compose
17-
- **CI/CD:** GitHub Actions
22+
| Layer | Technology |
23+
|-------|-----------|
24+
| Frontend | React 18, Vite, Axios |
25+
| Backend | Java 21, Spring Boot 3.5 |
26+
| Database | PostgreSQL |
27+
| ORM | Spring Data JPA / Hibernate |
28+
| AI | Groq API (LLaMA 3.3 70B) |
29+
| DevOps | Docker, Docker Compose, GitHub Actions |
30+
31+
---
1832

1933
## Risk Scoring Model
2034

21-
The engine scores companies from 0 (critical risk) to 100 (low risk) based on weighted security factors:
35+
```
36+
Base Score: 100
37+
38+
Deductions:
39+
-20 No firewall
40+
-15 No antivirus software
41+
-20 No data encryption
42+
-15 No incident response plan
43+
-10 No security training program
44+
-10 Per previous breach (×n)
2245
23-
| Factor | Penalty |
24-
|--------|---------|
25-
| No firewall | -20 pts |
26-
| No antivirus | -15 pts |
27-
| No data encryption | -20 pts |
28-
| No incident response plan | -15 pts |
29-
| No security training | -10 pts |
30-
| Each previous breach | -10 pts |
46+
Minimum score: 0
47+
```
3148

3249
| Score Range | Risk Level |
3350
|-------------|------------|
34-
| 80–100 | LOW |
35-
| 60–79 | MEDIUM |
36-
| 40–59 | HIGH |
37-
| 0–39 | CRITICAL |
51+
| 80 – 100 | LOW |
52+
| 60 – 79 | MEDIUM |
53+
| 40 – 59 | HIGH |
54+
| 0 – 39 | CRITICAL |
3855

39-
## API Endpoints
56+
---
4057

41-
| Method | Endpoint | Description |
42-
|--------|----------|-------------|
43-
| POST | `/api/companies` | Submit a company for assessment |
44-
| GET | `/api/companies` | Get all assessed companies |
45-
| GET | `/api/companies/{id}` | Get a specific company |
46-
| DELETE | `/api/companies/{id}` | Delete a company |
47-
| POST | `/api/companies/{id}/generate-memo` | Generate AI underwriting memo |
58+
## Getting Started
4859

49-
## Running Locally
60+
**Prerequisites:** Docker Desktop, Groq API key (free at [console.groq.com](https://console.groq.com))
5061

51-
### Prerequisites
52-
- Docker and Docker Compose
53-
- Groq API key (free at console.groq.com)
54-
55-
### Start the app
5662
```bash
63+
git clone https://github.com/sabrinahaniff/cyber-risk-platform.git
64+
cd cyber-risk-platform
65+
66+
# Run backend + database
5767
export GROQ_API_KEY=your_key_here
5868
docker-compose up --build
69+
70+
# Run frontend (new terminal)
71+
cd frontend
72+
npm install
73+
npm run dev
5974
```
6075

61-
The API will be available at `http://localhost:8080`
76+
- API: `http://localhost:8080`
77+
- UI: `http://localhost:5173`
78+
79+
---
6280

63-
### Example Request
81+
## API Endpoints
82+
83+
```
84+
POST /api/companies Create company assessment
85+
GET /api/companies Get all assessments
86+
GET /api/companies/:id Get by ID
87+
DELETE /api/companies/:id Delete assessment
88+
POST /api/companies/:id/generate-memo Generate AI underwriting memo
89+
```
90+
91+
**Example request:**
6492
```bash
6593
curl -X POST http://localhost:8080/api/companies \
66-
-H "Content-Type: application/json" \
67-
-d '{
68-
"name": "Acme Corp",
69-
"industry": "Finance",
70-
"employeeCount": 500,
71-
"country": "Canada",
72-
"hasFirewall": true,
73-
"hasAntiVirus": true,
74-
"encryptsData": false,
75-
"hasIncidentResponsePlan": false,
76-
"hasSecurityTraining": true,
77-
"previousBreaches": 2
78-
}'
94+
-H "Content-Type: application/json" \
95+
-d '{
96+
"name": "Acme Corp",
97+
"industry": "Finance",
98+
"employeeCount": 500,
99+
"country": "Canada",
100+
"hasFirewall": true,
101+
"hasAntiVirus": true,
102+
"encryptsData": false,
103+
"hasIncidentResponsePlan": false,
104+
"hasSecurityTraining": true,
105+
"previousBreaches": 2
106+
}'
79107
```
80108

81-
### Example Response
109+
**Response:**
82110
```json
83111
{
84112
"id": 1,
85113
"name": "Acme Corp",
86114
"industry": "Finance",
87115
"employeeCount": 500,
88116
"country": "Canada",
117+
"hasFirewall": true,
118+
"hasAntiVirus": true,
119+
"encryptsData": false,
120+
"hasIncidentResponsePlan": false,
121+
"hasSecurityTraining": true,
122+
"previousBreaches": 2,
89123
"riskScore": 45
90124
}
91125
```
92126

93-
### Generate Underwriting Memo
94-
```bash
95-
curl -X POST http://localhost:8080/api/companies/1/generate-memo
127+
---
128+
129+
## Project Structure
130+
131+
```
132+
cyber-risk-platform/
133+
├── src/main/java/com/cyberrisk/
134+
│ ├── controller/ # REST endpoints
135+
│ ├── service/ # Risk scoring + AI memo logic
136+
│ ├── repository/ # JPA repositories
137+
│ ├── model/ # Company entity
138+
│ └── config/ # CORS config
139+
├── frontend/
140+
│ └── src/
141+
│ ├── App.jsx # Main UI + risk gauge component
142+
│ └── App.css
143+
├── Dockerfile
144+
├── docker-compose.yml
145+
└── .github/workflows/
146+
└── ci.yml
96147
```
97148

98-
## Architecture
99-
REST API (Spring Boot)
100-
↓
101-
Risk Scoring Engine
102-
↓
103-
AI Memo Generator (Groq)
104-
↓
105-
PostgreSQL Database
149+
---
106150

107151
## CI/CD
108152

109-
GitHub Actions automatically builds and tests the application on every push to main.
153+
GitHub Actions runs on every push to `main`:
154+
155+
1. Spins up a PostgreSQL service container
156+
2. Builds the project with Maven
157+
3. Runs the test suite
158+
159+
[![CI Pipeline](https://github.com/sabrinahaniff/cyber-risk-platform/actions/workflows/ci.yml/badge.svg)](https://github.com/sabrinahaniff/cyber-risk-platform/actions/workflows/ci.yml)

0 commit comments

Comments
 (0)