Best Practices Document

[UlisesGascon]

This issue is just to keep tracking the work we've been doing in the Security WG. We've created a Best practices document targeting Node.js users.

This document intends to extend the current threat model and provide extensive guidelines (attacks explained, mitigations, etc..) on how to secure a Node.js application. It may change over releases.

Normally, the discussion around this document happens in the OpenJS Foundation slack (#nodejs-discussion-security-model and nodejs-security-wg). Feel free to contribute.

[RafaelGSS]

@nodejs/tsc We're about to create a pull request for the final review of this document. However, I'm not quite sure in which part of our documentation it would fit. Any advice?

While the Threat Model will take place on nodejs/node/THREAT_MODEL.md, this one was designed for Node.js users as a reference document.

[Trott]

While the Threat Model will take place on nodejs/node/THREAT_MODEL.md

We try to keep the top-level md files to a minimum. It might be better to either put the threat model in doc/contributing and link to it from SECURITY.md, or else put the THREAT_MODEL.md contents directly in SECURITY.md and not have a THREAD_MODEL.md at all.

[Trott]

this one was designed for Node.js users as a reference document.

It probably doesn't belong in the API reference docs but that's the one place we have user-facing documentation in the core repo. Maybe there's a sensible place withing doc/api. Otherwise, it needs to go somewhere on the website (the nodejs/nodejs.org repo and/or the nodejs/nodejs.dev repos) and that gets tricky because we're in the process of reducing content in those places. But if there is a commitment to actively maintain the doc and if it is of high value to users (and I think an authoritative best-security-practices high-level overview inherently is high-value), then we can find a place for it.

@nodejs/documentation @nodejs/website @nodejs/nodejs-dev

[RafaelGSS]

At the first moment, I'm thinking to include it into nodejs.org/en/docs/guides/security/ if no objections.

[ovflowd]

Is this supposed to be a security guide for end users? Interesting. It could be added within the Learn pages of Nodejs.dev but not 100% sure if it genuinely fits there...

Suppose this is going to be actively maintained, then sure. Also, @RafaelGSS, we're deprecating the guides from nodejs.org, as they're not even indexed at all/there's no navigation/reference.

[RafaelGSS]

Yes, that's supposed to be a security guide for end users.

Also, @RafaelGSS, we're deprecating the guides from nodejs.org, as they're not even indexed at all/there's no navigation/reference.

Wow, that's good to know. We're actively sending content there on the Diagnostics WG (see nodejs/diagnostics#502).

---

How can I include it in the Learn pages? Is there a similar PR I can use as a base?

[Trott]

Wow, that's good to know. We're actively sending content there on the Diagnostics WG (see nodejs/diagnostics#502).

I think the recently-updated and actively-maintained stuff is safe. This can be added there as well. If/when we completely eliminate the guides section, we'll move the few actively-maintained things somewhere else and put in a redirect. (Pinging @nodejs/build to confirm that adding a redirect in our nginx or whatever would be No Big Deal™.)

[RafaelGSS]

Alright, so I'll create the content there for now (nodejs.org/guides). Happy to help in the migration when the time comes.

[Trott]

How can I include it in the Learn pages? Is there a similar PR I can use as a base?

https://github.com/nodejs/nodejs.dev/tree/main/content/learn

[RafaelGSS]

I was looking at the 'Learn' content and it doesn't seem to fit there. The main reason is that all the content there looks like a real tutorial (for instance, how to manipulate files), and the Security Best Practices should be used as a reference/guide. It's not a tutorial at all.

[Trott]

I was looking at the 'Learn' content and it doesn't seem to fit there. The main reason is that all the content there looks like a real tutorial (for instance, how to manipulate files), and the Security Best Practices should be used as a reference/guide. It's not a tutorial at all.

I'd agree with that assessment. I want to definitely avoid scope creep in both places, so if it definitely fits in one and not the other, let's put it where it fits.

[ovflowd]

@Trott let's figure out during the next meeting about how to fit guides on nodejs.dev, we need somehow to be able to grab the essentials.

[Trott]

@Trott let's figure out during the next meeting about how to fit guides on nodejs.dev, we need somehow to be able to grab the essentials.

It's also possible that it lives someplace that isn't the website, but yeah, we need to figure out what that correct, official, authoritative place would be. (Seems like the website or maybe the GitHub repo are the two logical places.)

[Trott]

Maybe we end up mashing the tutorial and the guides into one section, with a very small number of tutorials in one subsection and a very small number of guides in the other subsection. Just an idea, though. Open to other ideas, of course.