vCSO-ai/ir-readiness-score
GitHub: vCSO-ai/ir-readiness-score
Stars: 0 | Forks: 0
# ir-readiness-score
[](https://opensource.org/licenses/MIT)
Score incident response preparedness across NIST SP 800-61 phases with gap analysis and MTTC estimation.
Evaluate your organization's IR readiness against 28 checklist items spanning all 6 NIST incident response phases, get a letter grade, identify prioritized remediation actions, and estimate your mean time to contain (MTTC) based on industry benchmarks.
## Install
**Python** (3.9+):
pip install ir-readiness-score
**JavaScript** (Node.js 16+):
npm install ir-readiness-score
## Quick Start
### Python
from ir_readiness_score import (
get_assessment_checklist,
score_readiness,
generate_priorities,
estimate_response_time,
)
# 1. Get the 28-item checklist grouped by NIST phase
checklist = get_assessment_checklist()
for phase in checklist:
print(f"{phase['label']}: {len(phase['items'])} items")
# 2. Score responses (each item rated 0-3)
responses = {
"prep-01": 3, # IR Policy — tested
"prep-02": 2, # IR Team — implemented
"detect-01": 1, # Monitoring — partial
# ... remaining items default to 0 (not implemented)
}
result = score_readiness(responses)
print(f"Overall: {result['overall_score']}% (Grade {result['grade']})")
print(f"Preparation: {result['phase_scores']['preparation']}%")
# 3. Get prioritized remediation actions
priorities = generate_priorities(responses)
for p in priorities[:5]:
print(f"[{p['impact'].upper()}] {p['title']} — gap: {p['gap']}, ~{p['effort_days']}d")
print(f" {p['recommendation']}")
# 4. Estimate mean time to contain
mttc = estimate_response_time(result["overall_score"])
print(f"Estimated MTTC: {mttc['mttc_hours']}h ({mttc['readiness_band']})")
print(mttc["benchmark_comparison"])
### JavaScript
const {
getAssessmentChecklist,
scoreReadiness,
generatePriorities,
estimateResponseTime,
} = require("ir-readiness-score");
// 1. Get the 28-item checklist grouped by NIST phase
const checklist = getAssessmentChecklist();
checklist.forEach((phase) =>
console.log(`${phase.label}: ${phase.items.length} items`)
);
// 2. Score responses (each item rated 0-3)
const responses = {
"prep-01": 3, // IR Policy — tested
"prep-02": 2, // IR Team — implemented
"detect-01": 1, // Monitoring — partial
// ... remaining items default to 0 (not implemented)
};
const result = scoreReadiness(responses);
console.log(`Overall: ${result.overallScore}% (Grade ${result.grade})`);
console.log(`Preparation: ${result.phaseScores.preparation}%`);
// 3. Get prioritized remediation actions
const priorities = generatePriorities(responses);
priorities.slice(0, 5).forEach((p) => {
console.log(`[${p.impact.toUpperCase()}] ${p.title} — gap: ${p.gap}, ~${p.effortDays}d`);
console.log(` ${p.recommendation}`);
});
// 4. Estimate mean time to contain
const mttc = estimateResponseTime(result.overallScore);
console.log(`Estimated MTTC: ${mttc.mttcHours}h (${mttc.readinessBand})`);
console.log(mttc.benchmarkComparison);
## API Reference
### `getAssessmentChecklist()` / `get_assessment_checklist()`
Returns the 28 checklist items grouped by NIST phase.
**Returns:** Array of phase objects, each with:
- `phase` (string) -- phase identifier
- `label` (string) -- human-readable phase name
- `items` (array) -- checklist items with `id`, `title`, `description`, and `scoring` (0-3 rubric)
### `scoreReadiness(responses)` / `score_readiness(responses)`
Score incident response readiness from checklist responses.
**Parameters:**
- `responses` (object/dict) -- mapping of checklist item IDs to scores (0-3). Unanswered items default to 0.
**Returns:**
- `overallScore` / `overall_score` (number) -- percentage 0-100
- `phaseScores` / `phase_scores` (object/dict) -- per-phase percentage
- `grade` (string) -- letter grade A/B/C/D/F
**Throws/Raises:** Error if an item ID is unknown or a score is outside 0-3.
### `readinessGrade(score)` / `readiness_grade(score)`
Map a readiness percentage (0-100) to a letter grade.
| Score Range | Grade |
|-------------|-------|
| 90-100 | A |
| 80-89 | B |
| 70-79 | C |
| 60-69 | D |
| 0-59 | F |
### `generatePriorities(responses)` / `generate_priorities(responses)`
Identify gaps and return prioritized remediation actions. Items are sorted by impact (high first), then gap size (largest first), then effort (quickest wins first).
**Returns:** Array of priority objects with:
- `id`, `title`, `phase`, `phaseLabel` / `phase_label`
- `currentScore` / `current_score` -- current maturity (0-3)
- `gap` -- points needed to reach maximum score
- `effortDays` / `effort_days` -- estimated calendar days to remediate
- `impact` -- high / medium / low
- `recommendation` -- next step to improve
### `estimateResponseTime(readinessScore)` / `estimate_response_time(readiness_score)`
Estimate mean time to contain (MTTC) based on readiness level, using industry benchmarks.
**Returns:**
- `mttcHours` / `mttc_hours` -- estimated hours to contain
- `mttcDays` / `mttc_days` -- estimated days to contain
- `readinessBand` / `readiness_band` -- band label
- `benchmarkComparison` / `benchmark_comparison` -- comparison to industry average
## Scoring System
Each of the 28 checklist items is scored on a 0-3 maturity scale:
| Score | Label | Meaning |
|-------|-------------|----------------------------------------------|
| 0 | None | Not implemented |
| 1 | Partial | Started but incomplete |
| 2 | Implemented | In place but not regularly tested |
| 3 | Tested | In place and validated through exercises |
## Checklist Overview
| Phase | Items | Coverage |
|----------------------|-------|-----------------------------------------------------------------------------|
| Preparation | 5 | IR policy, team, communication plan, toolkit, training |
| Detection & Analysis | 5 | Monitoring/logging, threat intel, classification, analysis, IOC management |
| Containment | 5 | Strategy, network segmentation, evidence, short/long-term, decision authority |
| Eradication | 5 | Root cause, malware removal, vulnerability remediation, credentials, verification |
| Recovery | 4 | Restoration plan, backup validation, monitoring during recovery, BC/DR integration |
| Lessons Learned | 4 | Post-incident review, metrics, process improvement, knowledge base |
## MTTC Benchmarks
Estimated mean time to contain (MTTC) by readiness band, based on composites from IBM X-Force, Ponemon, and SANS IR surveys:
| Readiness Band | Score Range | Estimated MTTC | Industry Comparison |
|----------------|-------------|----------------|--------------------------------|
| Excellent | 90-100% | 24 hours (1d) | 99% faster than average |
| Strong | 80-89% | 48 hours (2d) | 97% faster than average |
| Moderate | 70-79% | 96 hours (4d) | 95% faster than average |
| Weak | 60-69% | 168 hours (7d) | 90% faster than average |
| Critical | 0-59% | 336 hours (14d)| 81% faster than average |
Industry average MTTC: ~1,752 hours / 73 days (IBM Cost of a Data Breach Report, 2024).
## Further Reading
- For a complete incident response plan template with NIST phase mapping, see [Incident Response Plan Template](https://vcso.ai/learn/incident-response-plan-template/) on vCSO.ai.
- Test your IR plan with structured exercises -- read the [Cybersecurity Tabletop Exercises Guide](https://vcso.ai/learn/cybersecurity-tabletop-exercises/).
- To find the right managed security partner for IR support, see [Cybersecurity Services Provider Guide](https://vcso.ai/learn/cybersecurity-services-provider/).
## License
[MIT](LICENSE) -- Copyright (c) 2026 vCSO.ai