You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
@@ -12,9 +11,8 @@ Swagger 2.0 and OpenAPI 3.0 parser/validator
12
11
13
12
[](https://github.com/APIDevTools/swagger-parser/actions)
14
13
14
+
## Features
15
15
16
-
Features
17
-
--------------------------
18
16
- Parses Swagger specs in **JSON** or **YAML** format
19
17
- Validates against the [Swagger 2.0 schema](https://github.com/OAI/OpenAPI-Specification/blob/master/schemas/v2.0/schema.json) or [OpenAPI 3.0 Schema](https://github.com/OAI/OpenAPI-Specification/blob/master/schemas/v3.0/schema.json)
20
18
-[Resolves](https://apidevtools.com/swagger-parser/docs/swagger-parser.html#resolveapi-options-callback) all `$ref` pointers, including external files and URLs
@@ -25,24 +23,18 @@ Features
25
23
- Supports [circular references](https://apidevtools.com/swagger-parser/docs/#circular-refs), nested references, back-references, and cross-references
26
24
- Maintains object reference equality —`$ref` pointers to the same value always resolve to the same object instance
When using a transpiler such as [Babel](https://babeljs.io/) or [TypeScript](https://www.typescriptlang.org/), or a bundler such as [Webpack](https://webpack.js.org/) or [Rollup](https://rollupjs.org/), you can use **ECMAScript modules** syntax instead:
Swagger Parser supports recent versions of every major web browser. Older browsers may require [Babel](https://babeljs.io/) and/or [polyfills](https://babeljs.io/docs/en/next/babel-polyfill).
80
+
Swagger Parser supports recent versions of every major web browser. Older browsers may require [Babel](https://babeljs.io/) and/or [polyfills](https://babeljs.io/docs/en/next/babel-polyfill).
96
81
97
82
To use Swagger Parser in a browser, you'll need to use a bundling tool such as [Webpack](https://webpack.js.org/), [Rollup](https://rollupjs.org/), [Parcel](https://parceljs.org/), or [Browserify](http://browserify.org/). Some bundlers may require a bit of configuration, such as setting `browser: true` in [rollup-plugin-resolve](https://github.com/rollup/rollup-plugin-node-resolve).
98
83
84
+
## API Documentation
99
85
100
-
101
-
API Documentation
102
-
--------------------------
103
86
Full API documentation is available [right here](https://apidevtools.com/swagger-parser/docs/)
104
87
88
+
## Security
105
89
106
-
Security
107
-
--------------------------
108
90
The library, by default, attempts to resolve any files referenced using `$ref`, without considering file extensions or the location of the files. This can result in Local File Inclusion (LFI), thus, potentially sensitive information disclosure. Developers must be cautious when working with documents from untrusted sources. See [here](SECURITY.md) for more details and information on how to mitigate LFI.
109
91
92
+
## Contributing
110
93
111
-
Contributing
112
-
--------------------------
113
-
I welcome any contributions, enhancements, and bug-fixes. [Open an issue](https://github.com/APIDevTools/swagger-parser/issues) on GitHub and [submit a pull request](https://github.com/APIDevTools/swagger-parser/pulls).
94
+
I welcome any contributions, enhancements, and bug-fixes. [Open an issue](https://github.com/APIDevTools/swagger-parser/issues) on GitHub and [submit a pull request](https://github.com/APIDevTools/swagger-parser/pulls).
Swagger Parser is 100% free and open-source, under the [MIT license](LICENSE). Use it however you want.
132
113
133
114
This package is [Treeware](http://treeware.earth). If you use it in production, then we ask that you [**buy the world a tree**](https://shop.protect.earth) to thank us for our work.
134
115
116
+
## Big Thanks To
135
117
136
-
137
-
Big Thanks To
138
-
--------------------------
139
118
Thanks to these awesome companies for their support of Open Source developers ❤
Copy file name to clipboardExpand all lines: SECURITY.md
+13-13Lines changed: 13 additions & 13 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -6,9 +6,9 @@
6
6
7
7
The library, by default, attempts to resolve any files pointed to by `$ref`, which can be a problem in specific scenarios, for example:
8
8
9
-
* A backend service uses the library, AND
10
-
* The service processes OpenAPI documents from untrusted sources, AND
11
-
* The service performs actual requests based on the processed OpenAPI document
9
+
- A backend service uses the library, AND
10
+
- The service processes OpenAPI documents from untrusted sources, AND
11
+
- The service performs actual requests based on the processed OpenAPI document
12
12
13
13
For example, the below OpenAPI document refers to `/etc/passwd` via the `leak` property of the Pet object.
14
14
@@ -30,7 +30,7 @@ paths:
30
30
content:
31
31
application/json:
32
32
schema:
33
-
$ref: '#/components/schemas/Pet'
33
+
$ref: "#/components/schemas/Pet"
34
34
required: true
35
35
components:
36
36
schemas:
@@ -46,8 +46,8 @@ components:
46
46
example: 10
47
47
leak:
48
48
type: string
49
-
default:
50
-
$ref: '/etc/passwd'
49
+
default:
50
+
$ref: "/etc/passwd"
51
51
name:
52
52
type: string
53
53
example: doggie
@@ -110,16 +110,16 @@ Configuring the file resolver this way only partially mitigates LFI. See the nex
110
110
111
111
With the previously mentioned mitigation in place, an attacker could still craft a malicious OpenAPI document to make the library read arbitrary JSON or YAML files on the filesystem and potentially gain access to sensitive data (e.g. credentials). This is possible if:
112
112
113
-
* The actor knows (or successfully guesses) the location of a JSON or YAML file on the file system
114
-
* The service using the library has privileges to read the file
115
-
* The service using the library sends requests to the server specified in the OpenAPI document
113
+
- The actor knows (or successfully guesses) the location of a JSON or YAML file on the file system
114
+
- The service using the library has privileges to read the file
115
+
- The service using the library sends requests to the server specified in the OpenAPI document
116
116
117
117
You can prevent exploitation by hardening the environment in which the service is running:
118
118
119
-
* The service should run under its own dedicated user account
120
-
* File system permissions should be configured so that the service cannot read any YAML or JSON files not owned by the service user
119
+
- The service should run under its own dedicated user account
120
+
- File system permissions should be configured so that the service cannot read any YAML or JSON files not owned by the service user
121
121
122
122
If you have any YAML or JSON files the service must have access to that may contain sensitive information, such as configuration file(s), you must take additional measures to prevent exploitation. A non-exhaustive list:
123
123
124
-
* You can implement your service so that it reads the configuration into memory at start time, then uses [setuid](https://nodejs.org/api/process.html#processsetuidid) and [setgid](https://nodejs.org/api/process.html#processsetgidid) to set the process' UID and GID to the ID of a user and ID of a group that has no access to the file on the filesystem
125
-
* Do not store sensitive information, such as credentials, in the service configuration files
124
+
- You can implement your service so that it reads the configuration into memory at start time, then uses [setuid](https://nodejs.org/api/process.html#processsetuidid) and [setgid](https://nodejs.org/api/process.html#processsetgidid) to set the process' UID and GID to the ID of a user and ID of a group that has no access to the file on the filesystem
125
+
- Do not store sensitive information, such as credentials, in the service configuration files
0 commit comments