Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

reportingDescriptor name should mention pascal style constraint #20872

Open
1 task done
jsoref opened this issue Sep 25, 2022 · 26 comments · Fixed by #25368
Open
1 task done

reportingDescriptor name should mention pascal style constraint #20872

jsoref opened this issue Sep 25, 2022 · 26 comments · Fixed by #25368
Labels
code security Content related to code security. content This issue or pull request belongs to the Docs Content team help wanted Anyone is welcome to open a pull request to fix this issue.
Projects
Docs open source board

Comments

@jsoref
Copy link
Contributor

jsoref commented Sep 25, 2022 •
edited by felicitymay

Code of Conduct

What article on docs.github.com is affected?

https://docs.github.com/en/code-security/code-scanning/integrating-with-code-scanning/sarif-support-for-code-scanning#reportingdescriptor-object

What part(s) of the article would you like to see updated?

Name Description
name Optional. The name of the rule. Code scanning displays the name to allow results to be filtered by rule on GitHub.

Should mention:

SARIF2012: Rule metadata should provide information that makes it easy to understand and fix the problem. Provide the 'name' property, which contains a "friendly name" that helps users see at a glance the purpose of the rule. For uniformity of experience across all tools that produce SARIF, the friendly name should be a single Pascal-case identifier, for example, 'ProvideRuleFriendlyName'. Provide the 'helpUri' property, which contains a URI where users can find detailed information about the rule. This information should include a detailed description of the invalid pattern, an explanation of why the pattern is poor practice (particularly in contexts such as security or accessibility where driving considerations might not be readily apparent), guidance for resolving the problem (including describing circumstances in which ignoring the problem altogether might be appropriate), examples of invalid and valid patterns, and special considerations (such as noting when a violation should never be ignored or suppressed, noting when a violation could cause downstream tool noise, and noting when a rule can be configured in some way to refine or alter the analysis).

Additional information

Through a couple of levels of indirection, this page links to this page:
https://sarifweb.azurewebsites.net/Validation

And when I tried to validate my sarif file (checking the GitHub ingestion rules option), the validator screamed at me.

See steps to reproduce in: #20872 (comment)

Details of a separate problem...

Each item in this page should mention length and other constraints as well...

Name Description
name Optional. The name of the rule. Code scanning displays the name to allow results to be filtered by rule on GitHub.
shortDescription.text Required. A concise description of the rule. Code scanning displays the short description on GitHub next to the associated results.
fullDescription.text Required. A description of the rule. Code scanning displays the full description on GitHub next to the associated results. The max number of characters is limited to 1000.

fullDestription.text is limited to 1000 chars, but name and shortDescription.text aren't limited?

Content changes required to close this issue

  1. Update the description for the name field for the reportingDescriptor object to state that there are no restrictions on the format of the string.
  2. Add a note to the section on Validating your SARIF file:
    • Tell people that if there is a discrepancy between the SARIF validator results and the specification, the specification is correct.
    • Try uploading their SARIF file using the REST API with the validation flag.
    • When the validation flag is enabled, any validation errors are returned as the response body, with an error code immediately. This is a good method for debugging any errors that aren't detected by the SARIF validator, or cases where the validator and schema contradict each other.
@jsoref jsoref added the content This issue or pull request belongs to the Docs Content team label Sep 25, 2022
@github-actions github-actions bot added the triage Do not begin working on this issue until triaged by the team. label Sep 25, 2022
@cmwilson21
Copy link
Contributor

👋 @jsoref - Thanks so much for opening an issue! I'll triage this for the team to take a look 👀

@cmwilson21 cmwilson21 added waiting for review Issue/PR is waiting for a writer's review code security Content related to code security. and removed triage Do not begin working on this issue until triaged by the team. labels Sep 26, 2022
@felicitymay
Copy link
Contributor

Thanks for flagging this @jsoref - much appreciated.

Each item in this page should mention length and other constraints as well...

I'm going to tag this for an SME to take a look and advise on this. Then we'll add update the issue summary with details of the content changes needed.

@felicitymay felicitymay added the needs SME This proposal needs review from a subject matter expert. label Sep 28, 2022
@github-actions
Copy link
Contributor

Thanks for opening an issue! We've triaged this issue for technical review by a subject matter expert 👀

@github-actions
Copy link
Contributor

This is a gentle bump for the docs team that this issue is waiting for technical review.

@github-actions github-actions bot added the SME stale The request for an SME has staled. label Oct 26, 2022
@cmwilson21 cmwilson21 removed the SME stale The request for an SME has staled. label Oct 27, 2022
@github-actions
Copy link
Contributor

This is a gentle bump for the docs team that this issue is waiting for technical review.

@github-actions github-actions bot added the SME stale The request for an SME has staled. label Nov 24, 2022
@cmwilson21 cmwilson21 removed the SME stale The request for an SME has staled. label Nov 25, 2022
@github-actions
Copy link
Contributor

This is a gentle bump for the docs team that this issue is waiting for technical review.

@github-actions github-actions bot added SME stale The request for an SME has staled. and removed SME stale The request for an SME has staled. labels Dec 24, 2022
@github-actions
Copy link
Contributor

This is a gentle bump for the docs team that this issue is waiting for technical review.

@github-actions github-actions bot added the SME stale The request for an SME has staled. label Jan 23, 2023
@cmwilson21 cmwilson21 removed the SME stale The request for an SME has staled. label Jan 24, 2023
@github-actions
Copy link
Contributor

This is a gentle bump for the docs team that this issue is waiting for technical review.

@github-actions github-actions bot added the SME stale The request for an SME has staled. label Feb 21, 2023
@cmwilson21 cmwilson21 removed the SME stale The request for an SME has staled. label Feb 21, 2023
@github-actions
Copy link
Contributor

This is a gentle bump for the docs team that this issue is waiting for technical review.

@github-actions github-actions bot added the SME stale The request for an SME has staled. label Mar 22, 2023
@cmwilson21 cmwilson21 removed the SME stale The request for an SME has staled. label Mar 23, 2023
@simon-engledew
Copy link
Contributor

Each item in this page should mention length and other constraints as well...

The limits on the three fields in that table are:

  • Name - 255 characters
  • ShortDescription.Text - 1024 characters
  • FullDescription.Text - 1024 characters

@cmwilson21 cmwilson21 added SME reviewed An SME has reviewed this issue/PR and removed needs SME This proposal needs review from a subject matter expert. labels Mar 30, 2023
@felicitymay
Copy link
Contributor

@jsoref - many thanks for the clear reproduction steps. I'll tag this for an SME review.

@felicitymay felicitymay added needs SME This proposal needs review from a subject matter expert. and removed SME reviewed An SME has reviewed this issue/PR question labels May 4, 2023
@github-actions
Copy link
Contributor

github-actions bot commented May 4, 2023

Thanks for opening an issue! We've triaged this issue for technical review by a subject matter expert 👀

@felicitymay felicitymay removed their assignment May 15, 2023
@github-actions
Copy link
Contributor

This is a gentle bump for the docs team that this issue is waiting for technical review.

@github-actions github-actions bot added the SME stale The request for an SME has staled. label Jun 12, 2023
@cmwilson21 cmwilson21 removed the SME stale The request for an SME has staled. label Jun 13, 2023
@github-actions
Copy link
Contributor

This is a gentle bump for the docs team that this issue is waiting for technical review.

@github-actions github-actions bot added the SME stale The request for an SME has staled. label Jul 11, 2023
@cmwilson21 cmwilson21 removed the SME stale The request for an SME has staled. label Jul 12, 2023
@github-actions
Copy link
Contributor

github-actions bot commented Aug 9, 2023

This is a gentle bump for the docs team that this issue is waiting for technical review.

@github-actions github-actions bot added the SME stale The request for an SME has staled. label Aug 9, 2023
@cmwilson21 cmwilson21 removed the SME stale The request for an SME has staled. label Aug 10, 2023
@github-actions
Copy link
Contributor

github-actions bot commented Sep 7, 2023

This is a gentle bump for the docs team that this issue is waiting for technical review.

@github-actions github-actions bot added the SME stale The request for an SME has staled. label Sep 7, 2023
@cmwilson21 cmwilson21 removed the SME stale The request for an SME has staled. label Sep 8, 2023
@felicitymay
Copy link
Contributor

felicitymay commented Sep 18, 2023 •
edited

Hi @jsoref 👋🏻

Apologies for the delay in getting back to you.

I can confirm that there is no need to use Pascal case for the reportingDescriptor name property. The SARIF specification sets no limits on the text for this field, see 3.49.7 name property. I agree with you that the example is misleading.

Proposed actions:

  • Let Microsoft know that they need to update the validation for GitHub ingestion rules.
  • Update the description for this field to state that there are no restrictions on the format of the string.
  • Add a note to the section on validating your SARIF file to let people know that if there is a discrepancy between the validator results and the specification, the specification is correct. They should try uploading their SARIF file using the REST API with the validation flag. When the validation flag is enabled, any validation errors are returned as the response body, with an error code immediately. This allows for faster debugging.

I think this will make this clearer in the docs and hopefully the validator will be updated soon.

@jsoref
Copy link
Contributor Author

jsoref commented Sep 18, 2023

I don't see the validation flag in the REST documentation?

@felicitymay
Copy link
Contributor

I didn't find it easily either. It's the last body parameter:

image

@jsoref
Copy link
Contributor Author

jsoref commented Sep 18, 2023 •
edited

Oh, I think either your anchor was for an earlier object or my GitHub Mobile for Android is not doing me any favors. In theory the link should be to:

https://docs.github.com/en/rest/code-scanning/code-scanning?apiVersion=2022-11-28#upload-an-analysis-as-sarif-data

Disclaimer: I'm using GitHub Mobile for Android beta, and it's possible that it's doing a bad job of jumping to the anchor.

Specifically, this is what I see when I click the link:

Screenshot_20230918-085837.png
Reported as https://github.com/orgs/community/discussions/67482

Do note that it would be really helpful to be able to link to parameters either as a section or as individual items, and neither are easy to do today.

@felicitymay
Copy link
Contributor

Interesting. That is the same link that I gave.

I can certainly raise a request to look into the possibility of making more anchors available on the page. I suspect that there may be concerns with adding more visual distraction to the page, but the only way to find out is to ask.

@jsoref
Copy link
Contributor Author

jsoref commented Sep 18, 2023

I can understand the concern about visual clutter. If the additional anchors didn't have the magic visual distinctions and were only discoverable via DOM Inspection, I'd still take the half-improvement as people like you and me could produce them (using a typical desktop web browser) and everyone could benefit from consuming them (as long as our HTML user agent isn't broken – see discussion linked from edited comment above).

@github-actions
Copy link
Contributor

This is a gentle bump for the docs team that this issue is waiting for technical review.

@github-actions github-actions bot added the SME stale The request for an SME has staled. label Oct 16, 2023
@cmwilson21 cmwilson21 removed the SME stale The request for an SME has staled. label Oct 16, 2023
@felicitymay felicitymay added help wanted Anyone is welcome to open a pull request to fix this issue. and removed needs SME This proposal needs review from a subject matter expert. labels Oct 23, 2023
@docs-bot docs-bot added this to Help wanted in Docs open source board Oct 23, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
code security Content related to code security. content This issue or pull request belongs to the Docs Content team help wanted Anyone is welcome to open a pull request to fix this issue.
Projects
Docs open source board
Help wanted
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

Add SARIF limits provided by SME github/docs
7 participants
@simon-engledew @felicitymay @jsoref @cmwilson21 and others