mirror of
https://github.com/nlohmann/json.git
synced 2026-10-03 13:10:33 +00:00
deploy: cc472af13f
This commit is contained in:
nlohmann
@@ -0,0 +1,70 @@
|
||||
# Assurance case
|
||||
|
||||
This page argues why the library meets its security requirements. It describes the threats the library faces, where the
|
||||
trust boundaries lie, and how the library's design and the [quality assurance](quality_assurance.md) counter these
|
||||
threats. To report a vulnerability, see the [security policy](security_policy.md).
|
||||
|
||||
## Threat model
|
||||
|
||||
The library parses, stores, and serializes JSON values in memory. It does not open network connections, does not open
|
||||
files (it only reads from streams or `std::FILE*` handles that the caller has already opened), does not read environment
|
||||
variables, and does not implement cryptography or handle credentials.
|
||||
|
||||
The primary threat is therefore **untrusted input**: JSON text or binary data (BJData, BSON, CBOR, MessagePack, UBJSON)
|
||||
that an attacker controls, passed to [`parse`](../api/basic_json/parse.md), [`accept`](../api/basic_json/accept.md),
|
||||
[`sax_parse`](../api/basic_json/sax_parse.md), or one of the `from_*` functions such as
|
||||
[`from_cbor`](../api/basic_json/from_cbor.md). Such input may try to
|
||||
|
||||
- make the library read or write out of bounds (malformed lengths, truncated input, invalid UTF-8),
|
||||
- trigger undefined behavior (integer overflow in sizes or numbers, invalid casts),
|
||||
- exhaust memory (huge announced sizes), or
|
||||
- exhaust the call stack (deeply nested arrays and objects).
|
||||
|
||||
## Trust boundaries
|
||||
|
||||
- **Untrusted:** all serialized input read by the parser, the SAX interface, and the binary readers. The library must
|
||||
handle every possible input by either producing a value or throwing a [`parse_error`](../home/exceptions.md#parse-errors)
|
||||
(or returning `false` when exceptions are disabled for the call).
|
||||
- **Trusted:** the C++ code that calls the library. Calling a function with violated preconditions, for instance
|
||||
accessing an array with [`operator[]`](../api/basic_json/operator%5B%5D.md) out of range, is a programming error and
|
||||
not a security boundary. Such preconditions are checked with [runtime assertions](../features/assertions.md) in debug
|
||||
builds; functions such as [`at`](../api/basic_json/at.md) offer checked access with exceptions.
|
||||
|
||||
## Secure design
|
||||
|
||||
- **Strict parsing.** The parser accepts exactly the JSON grammar of [RFC 8259](https://datatracker.ietf.org/doc/html/rfc8259).
|
||||
Extensions such as [comments](../features/comments.md) and [trailing commas](../features/trailing_commas.md) must be
|
||||
enabled explicitly. Invalid UTF-8 is rejected.
|
||||
- **Errors are reported, not ignored.** Malformed input results in a [`parse_error`](../home/exceptions.md#parse-errors)
|
||||
with the byte position of the error. Binary readers do not trust announced sizes: strings and binary values grow
|
||||
only as bytes are actually read, arrays reserve at most a fixed number of elements up front, and sizes that no
|
||||
container can hold are rejected.
|
||||
- **Memory is owned by values.** Each `basic_json` value owns its content, and there is no manual memory management in
|
||||
user code. The destructor does not recurse, so destroying a deeply nested value does not exhaust the stack.
|
||||
- **Bounded recursion.** The JSON parser and the binary readers keep their state in explicit stacks instead of
|
||||
recursing per nesting level. Operations that walk a value, such as [`dump`](../api/basic_json/dump.md), copying,
|
||||
hashing, and [`merge_patch`](../api/basic_json/merge_patch.md), recurse only up to a fixed depth and continue with an
|
||||
explicit stack below it. Some operations, such as comparison, [`diff`](../api/basic_json/diff.md),
|
||||
[`flatten`](../api/basic_json/flatten.md), and the binary writers, still recurse once per nesting level; work on them
|
||||
is in progress. Applications that process untrusted input can limit its nesting depth with a
|
||||
[parser callback](../features/parsing/parser_callbacks.md).
|
||||
- **Invariants are checked.** The class invariant (for instance, that the pointer for the stored type is never null) is
|
||||
checked with runtime assertions throughout the test suite.
|
||||
|
||||
## Common weaknesses
|
||||
|
||||
The following table maps the relevant classes of the [Common Weakness Enumeration](https://cwe.mitre.org) to the
|
||||
measures that counter them. The measures are described in detail in [Quality assurance](quality_assurance.md).
|
||||
|
||||
| Weakness | Countermeasures |
|
||||
|---------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------|
|
||||
| Out-of-bounds read/write ([CWE-125](https://cwe.mitre.org/data/definitions/125.html), [CWE-787](https://cwe.mitre.org/data/definitions/787.html)) | bounds checks on all reads from the input; AddressSanitizer and Valgrind on the test suite; OSS-Fuzz |
|
||||
| Integer overflow ([CWE-190](https://cwe.mitre.org/data/definitions/190.html)) | UndefinedBehaviorSanitizer with integer overflow detection; Clang-Tidy; Cppcheck |
|
||||
| Use after free, double free ([CWE-416](https://cwe.mitre.org/data/definitions/416.html), [CWE-415](https://cwe.mitre.org/data/definitions/415.html)) | ownership of all memory by values; AddressSanitizer and Valgrind; Clang Static Analyzer |
|
||||
| Memory leaks ([CWE-401](https://cwe.mitre.org/data/definitions/401.html)) | Valgrind (Memcheck) on the test suite |
|
||||
| Uncontrolled recursion ([CWE-674](https://cwe.mitre.org/data/definitions/674.html)) | iterative parser, binary readers, and destructor; bounded recursion in value operations; tests with deeply nested inputs |
|
||||
| Uncontrolled resource consumption ([CWE-400](https://cwe.mitre.org/data/definitions/400.html)) | allocations based on announced sizes are capped; OSS-Fuzz with memory limits |
|
||||
| Undefined behavior in general ([CWE-758](https://cwe.mitre.org/data/definitions/758.html)) | UndefinedBehaviorSanitizer; runtime assertions; Clang-Tidy, Cppcheck, Clang Static Analyzer, Infer |
|
||||
|
||||
In addition, every line of the library is covered by the unit tests, and all parsers are fuzz-tested around the clock
|
||||
by [OSS-Fuzz](https://github.com/google/oss-fuzz/tree/master/projects/json).
|
||||
File diff suppressed because one or more lines are too long
@@ -0,0 +1,43 @@
|
||||
# Assurance case
|
||||
|
||||
This page argues why the library meets its security requirements. It describes the threats the library faces, where the trust boundaries lie, and how the library's design and the [quality assurance](https://json.nlohmann.me/community/quality_assurance/index.md) counter these threats. To report a vulnerability, see the [security policy](https://json.nlohmann.me/community/security_policy/index.md).
|
||||
|
||||
## Threat model
|
||||
|
||||
The library parses, stores, and serializes JSON values in memory. It does not open network connections, does not open files (it only reads from streams or `std::FILE*` handles that the caller has already opened), does not read environment variables, and does not implement cryptography or handle credentials.
|
||||
|
||||
The primary threat is therefore **untrusted input**: JSON text or binary data (BJData, BSON, CBOR, MessagePack, UBJSON) that an attacker controls, passed to [`parse`](https://json.nlohmann.me/api/basic_json/parse/index.md), [`accept`](https://json.nlohmann.me/api/basic_json/accept/index.md), [`sax_parse`](https://json.nlohmann.me/api/basic_json/sax_parse/index.md), or one of the `from_*` functions such as [`from_cbor`](https://json.nlohmann.me/api/basic_json/from_cbor/index.md). Such input may try to
|
||||
|
||||
- make the library read or write out of bounds (malformed lengths, truncated input, invalid UTF-8),
|
||||
- trigger undefined behavior (integer overflow in sizes or numbers, invalid casts),
|
||||
- exhaust memory (huge announced sizes), or
|
||||
- exhaust the call stack (deeply nested arrays and objects).
|
||||
|
||||
## Trust boundaries
|
||||
|
||||
- **Untrusted:** all serialized input read by the parser, the SAX interface, and the binary readers. The library must handle every possible input by either producing a value or throwing a [`parse_error`](https://json.nlohmann.me/home/exceptions/#parse-errors) (or returning `false` when exceptions are disabled for the call).
|
||||
- **Trusted:** the C++ code that calls the library. Calling a function with violated preconditions, for instance accessing an array with [`operator[]`](https://json.nlohmann.me/api/basic_json/operator%5B%5D/index.md) out of range, is a programming error and not a security boundary. Such preconditions are checked with [runtime assertions](https://json.nlohmann.me/features/assertions/index.md) in debug builds; functions such as [`at`](https://json.nlohmann.me/api/basic_json/at/index.md) offer checked access with exceptions.
|
||||
|
||||
## Secure design
|
||||
|
||||
- **Strict parsing.** The parser accepts exactly the JSON grammar of [RFC 8259](https://datatracker.ietf.org/doc/html/rfc8259). Extensions such as [comments](https://json.nlohmann.me/features/comments/index.md) and [trailing commas](https://json.nlohmann.me/features/trailing_commas/index.md) must be enabled explicitly. Invalid UTF-8 is rejected.
|
||||
- **Errors are reported, not ignored.** Malformed input results in a [`parse_error`](https://json.nlohmann.me/home/exceptions/#parse-errors) with the byte position of the error. Binary readers do not trust announced sizes: strings and binary values grow only as bytes are actually read, arrays reserve at most a fixed number of elements up front, and sizes that no container can hold are rejected.
|
||||
- **Memory is owned by values.** Each `basic_json` value owns its content, and there is no manual memory management in user code. The destructor does not recurse, so destroying a deeply nested value does not exhaust the stack.
|
||||
- **Bounded recursion.** The JSON parser and the binary readers keep their state in explicit stacks instead of recursing per nesting level. Operations that walk a value, such as [`dump`](https://json.nlohmann.me/api/basic_json/dump/index.md), copying, hashing, and [`merge_patch`](https://json.nlohmann.me/api/basic_json/merge_patch/index.md), recurse only up to a fixed depth and continue with an explicit stack below it. Some operations, such as comparison, [`diff`](https://json.nlohmann.me/api/basic_json/diff/index.md), [`flatten`](https://json.nlohmann.me/api/basic_json/flatten/index.md), and the binary writers, still recurse once per nesting level; work on them is in progress. Applications that process untrusted input can limit its nesting depth with a [parser callback](https://json.nlohmann.me/features/parsing/parser_callbacks/index.md).
|
||||
- **Invariants are checked.** The class invariant (for instance, that the pointer for the stored type is never null) is checked with runtime assertions throughout the test suite.
|
||||
|
||||
## Common weaknesses
|
||||
|
||||
The following table maps the relevant classes of the [Common Weakness Enumeration](https://cwe.mitre.org) to the measures that counter them. The measures are described in detail in [Quality assurance](https://json.nlohmann.me/community/quality_assurance/index.md).
|
||||
|
||||
| Weakness | Countermeasures |
|
||||
| ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
|
||||
| Out-of-bounds read/write ([CWE-125](https://cwe.mitre.org/data/definitions/125.html), [CWE-787](https://cwe.mitre.org/data/definitions/787.html)) | bounds checks on all reads from the input; AddressSanitizer and Valgrind on the test suite; OSS-Fuzz |
|
||||
| Integer overflow ([CWE-190](https://cwe.mitre.org/data/definitions/190.html)) | UndefinedBehaviorSanitizer with integer overflow detection; Clang-Tidy; Cppcheck |
|
||||
| Use after free, double free ([CWE-416](https://cwe.mitre.org/data/definitions/416.html), [CWE-415](https://cwe.mitre.org/data/definitions/415.html)) | ownership of all memory by values; AddressSanitizer and Valgrind; Clang Static Analyzer |
|
||||
| Memory leaks ([CWE-401](https://cwe.mitre.org/data/definitions/401.html)) | Valgrind (Memcheck) on the test suite |
|
||||
| Uncontrolled recursion ([CWE-674](https://cwe.mitre.org/data/definitions/674.html)) | iterative parser, binary readers, and destructor; bounded recursion in value operations; tests with deeply nested inputs |
|
||||
| Uncontrolled resource consumption ([CWE-400](https://cwe.mitre.org/data/definitions/400.html)) | allocations based on announced sizes are capped; OSS-Fuzz with memory limits |
|
||||
| Undefined behavior in general ([CWE-758](https://cwe.mitre.org/data/definitions/758.html)) | UndefinedBehaviorSanitizer; runtime assertions; Clang-Tidy, Cppcheck, Clang Static Analyzer, Infer |
|
||||
|
||||
In addition, every line of the library is covered by the unit tests, and all parsers are fuzz-tested around the clock by [OSS-Fuzz](https://github.com/google/oss-fuzz/tree/master/projects/json).
|
||||
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
@@ -5,4 +5,6 @@
|
||||
- [Contribution Guidelines](https://json.nlohmann.me/community/contribution_guidelines/index.md) - guidelines how to contribute to this project
|
||||
- [Governance](https://json.nlohmann.me/community/governance/index.md) - the governance model of this project
|
||||
- [Quality Assurance](https://json.nlohmann.me/community/quality_assurance/index.md) - how the quality of this project is assured
|
||||
- [Roadmap](https://json.nlohmann.me/community/roadmap/index.md) - what the project will and will not do
|
||||
- [Security Policy](https://json.nlohmann.me/community/security_policy/index.md) - the security policy of the project
|
||||
- [Assurance Case](https://json.nlohmann.me/community/assurance_case/index.md) - why the library meets its security requirements
|
||||
|
||||
@@ -164,6 +164,9 @@ Note: Some modern features (like C++20 ranges or filesystem support) may be disa
|
||||
- [x] The parser is tested against extensive correctness suites for JSON compliance.
|
||||
- [x] In addition, the library is continuously fuzz-tested at [OSS-Fuzz](https://google.github.io/oss-fuzz/) where the
|
||||
library is checked against billions of inputs.
|
||||
- [x] Every crash reported by OSS-Fuzz is fixed together with a unit test that reproduces it, and the fix references
|
||||
the OSS-Fuzz issue. The round-trip checks of the fuzzer drivers are also part of the unit tests. See the
|
||||
[fuzz testing documentation](https://github.com/nlohmann/json/blob/develop/tests/fuzzing.md#handling-oss-fuzz-reports).
|
||||
|
||||
## Static analysis
|
||||
|
||||
|
||||
File diff suppressed because one or more lines are too long
@@ -547,6 +547,7 @@ The library is compliant to JSON as defined in [RFC 8259](https://datatracker.ie
|
||||
- The lexer is tested with all valid Unicode code points and all prefixes of all invalid Unicode code points.
|
||||
- The parser is tested against extensive correctness suites for JSON compliance.
|
||||
- In addition, the library is continuously fuzz-tested at [OSS-Fuzz](https://google.github.io/oss-fuzz/) where the library is checked against billions of inputs.
|
||||
- Every crash reported by OSS-Fuzz is fixed together with a unit test that reproduces it, and the fix references the OSS-Fuzz issue. The round-trip checks of the fuzzer drivers are also part of the unit tests. See the [fuzz testing documentation](https://github.com/nlohmann/json/blob/develop/tests/fuzzing.md#handling-oss-fuzz-reports).
|
||||
|
||||
## Static analysis
|
||||
|
||||
|
||||
@@ -0,0 +1,43 @@
|
||||
# Roadmap
|
||||
|
||||
This page describes what the project intends to do, and what it does not intend to do, over the next year. Concrete
|
||||
work items are tracked in the [GitHub milestones](https://github.com/nlohmann/json/milestones) and the
|
||||
[issue tracker](https://github.com/nlohmann/json/issues).
|
||||
|
||||
## What the project will do
|
||||
|
||||
- **Keep the C++11 baseline.** The library will continue to compile with every
|
||||
[supported C++11 compiler](https://github.com/nlohmann/json/blob/develop/README.md#supported-compilers). Features of
|
||||
later standards are only used when they are guarded by the `JSON_HAS_CPP_*` macros.
|
||||
- **Stay conformant to JSON.** The parser and serializer follow [RFC 8259](https://datatracker.ietf.org/doc/html/rfc8259).
|
||||
Extensions such as [comments](../features/comments.md) or [trailing commas](../features/trailing_commas.md) remain
|
||||
opt-in.
|
||||
- **Keep the 3.x public API stable.** Releases follow [semantic versioning](https://semver.org). Changes that would
|
||||
break existing code are only added behind a feature macro, so users can opt in and test their code before a next
|
||||
major release.
|
||||
- **Support a broad range of compilers and platforms.** The [CI](quality_assurance.md) keeps testing old and new
|
||||
versions of GCC, Clang, MSVC, and other compilers on Linux, macOS, and Windows.
|
||||
- **Keep the quality assurance up.** Every change keeps the test coverage at 100%, passes the static and dynamic
|
||||
analysis, and is fuzz-tested by OSS-Fuzz, see [Quality assurance](quality_assurance.md).
|
||||
- **Harden the library against hostile input.** Handling deeply nested values without exhausting the call stack is
|
||||
ongoing work.
|
||||
- **Fix bugs and security issues** reported through the issue tracker and the [security policy](security_policy.md).
|
||||
|
||||
## What the project will not do
|
||||
|
||||
- **Break the public API of version 3.x.** See the
|
||||
[contribution guidelines](https://github.com/nlohmann/json/blob/develop/.github/CONTRIBUTING.md#break-the-public-api)
|
||||
for what counts as a breaking change.
|
||||
- **Require a newer C++ standard than C++11.**
|
||||
- **Break JSON conformance** or enable non-standard extensions by default.
|
||||
- **Add dependencies** or require a build step. The library remains header-only, and the single header
|
||||
`json.hpp` remains a complete distribution.
|
||||
- **Trade simplicity for speed or memory efficiency.** Performance improvements are welcome, but the library is not
|
||||
meant to compete with the fastest JSON libraries, see [Design goals](../home/design_goals.md).
|
||||
|
||||
## Version 4.0
|
||||
|
||||
There is no decision yet on whether or when a version 4.0 with breaking changes will be released. Proposals that need
|
||||
a major version, for instance stricter type conversions, are collected in issue
|
||||
[#3453](https://github.com/nlohmann/json/issues/3453). Until then, such changes are only added as opt-in behavior
|
||||
behind feature macros.
|
||||
File diff suppressed because one or more lines are too long
@@ -0,0 +1,25 @@
|
||||
# Roadmap
|
||||
|
||||
This page describes what the project intends to do, and what it does not intend to do, over the next year. Concrete work items are tracked in the [GitHub milestones](https://github.com/nlohmann/json/milestones) and the [issue tracker](https://github.com/nlohmann/json/issues).
|
||||
|
||||
## What the project will do
|
||||
|
||||
- **Keep the C++11 baseline.** The library will continue to compile with every [supported C++11 compiler](https://github.com/nlohmann/json/blob/develop/README.md#supported-compilers). Features of later standards are only used when they are guarded by the `JSON_HAS_CPP_*` macros.
|
||||
- **Stay conformant to JSON.** The parser and serializer follow [RFC 8259](https://datatracker.ietf.org/doc/html/rfc8259). Extensions such as [comments](https://json.nlohmann.me/features/comments/index.md) or [trailing commas](https://json.nlohmann.me/features/trailing_commas/index.md) remain opt-in.
|
||||
- **Keep the 3.x public API stable.** Releases follow [semantic versioning](https://semver.org). Changes that would break existing code are only added behind a feature macro, so users can opt in and test their code before a next major release.
|
||||
- **Support a broad range of compilers and platforms.** The [CI](https://json.nlohmann.me/community/quality_assurance/index.md) keeps testing old and new versions of GCC, Clang, MSVC, and other compilers on Linux, macOS, and Windows.
|
||||
- **Keep the quality assurance up.** Every change keeps the test coverage at 100%, passes the static and dynamic analysis, and is fuzz-tested by OSS-Fuzz, see [Quality assurance](https://json.nlohmann.me/community/quality_assurance/index.md).
|
||||
- **Harden the library against hostile input.** Handling deeply nested values without exhausting the call stack is ongoing work.
|
||||
- **Fix bugs and security issues** reported through the issue tracker and the [security policy](https://json.nlohmann.me/community/security_policy/index.md).
|
||||
|
||||
## What the project will not do
|
||||
|
||||
- **Break the public API of version 3.x.** See the [contribution guidelines](https://github.com/nlohmann/json/blob/develop/.github/CONTRIBUTING.md#break-the-public-api) for what counts as a breaking change.
|
||||
- **Require a newer C++ standard than C++11.**
|
||||
- **Break JSON conformance** or enable non-standard extensions by default.
|
||||
- **Add dependencies** or require a build step. The library remains header-only, and the single header `json.hpp` remains a complete distribution.
|
||||
- **Trade simplicity for speed or memory efficiency.** Performance improvements are welcome, but the library is not meant to compete with the fastest JSON libraries, see [Design goals](https://json.nlohmann.me/home/design_goals/index.md).
|
||||
|
||||
## Version 4.0
|
||||
|
||||
There is no decision yet on whether or when a version 4.0 with breaking changes will be released. Proposals that need a major version, for instance stricter type conversions, are collected in issue [#3453](https://github.com/nlohmann/json/issues/3453). Until then, such changes are only added as opt-in behavior behind feature macros.
|
||||
File diff suppressed because one or more lines are too long
Reference in New Issue
Block a user